Features
Features are your product catalog: a tree of what your product does, where each feature has a specification. Create, update, move and search features, link them to the applications that implement them and to the features they depend on, and read their business rules and document history. Have Productmind draft a specification, refresh it from the linked code for your review or suggest tasks, and find the features that own the files a change touched. See Features.
List product features in a workspace
Returns the feature catalog for a workspace. Features represent product capabilities organized in a hierarchy with parent/child relationships. Returns: id, displayId, title, priority, status, parentFeatureId, parentFeature (a lean ancestry breadcrumb), subFeatureCount, sortOrder. Descriptions are NOT included — a workspace of fully-specified features runs to megabytes, which exceeds what one tool call can return; read a specific feature's markdown with get-feature, or search across them with search-features. Pass ?includeDescription=true only if you genuinely need every description at once.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
parentFeatureIdParent feature UUID, or 'all' for all features
kindFilter by tier (single value or array). component returns only the code-owning leaves — the rows that carry business rules and that a component read scans; feature returns the business capabilities above them; domain returns only the hand-curated collections above THOSE, which own no code and are never scanned. feature does NOT include domains, so enumerating "everything above components" means passing both.
priorityFilter by priority (single value or array)
statusFilter by status (single value or array)
ownerIdFilter by assignee (historically 'owner'): a user or team UUID, or a comma-separated list of them (features assigned to ANY listed user/team match). my-teams stands for every team the caller belongs to, and for-me for the features FOR the caller: assigned to them, or in the area of a team they are on (assigned to the team or anywhere under a feature that is). for-me is the sidebar's Features counts.
teamIdFilter to a TEAM's area: a team UUID, or a comma-separated list of them (items in the area of ANY listed team match). my-teams stands for every team the caller belongs to. An item is in a team's area when it is assigned to the team, or sits under a feature assigned to it, at any depth: a feature's sub-features, their tasks and sub-tasks, the bug reports linked to those features and tasks, and the coding sessions working on them. Unlike assigneeId, which matches only items assigned directly. A user id matches nothing, and so does my-teams for a caller on no team. This list returns root features unless parentFeatureId is given: pass parentFeatureId=all for the team's whole area, sub-features included. The sub-feature listing does not apply it.
externalSourceFilter by externalSource marker (e.g. 'system_generated' to surface agent-suggested starter features).
tagsComma-separated tag names to filter by
applicationFilter by LINKED APPLICATION: a single application UUID, or a comma-separated list of them (features linked to ANY listed application match). The link is the feature's own depends_on → application edge — a parent whose CHILDREN are linked does not match. Top-level rows only; the sub-feature listing does not apply it.
codeSurfaceFilter by whether a CODE SURFACE is recorded on the feature's application links. recorded: at least one linked application carries code paths or entry points (from a scan or added by hand). missing: no linked application carries any — which includes features with no application link at all. Top-level rows only; the sub-feature listing does not apply it.
deepScanFilter by DEEP SCAN status (single value or array; a feature matching ANY listed value is returned). scanned: a scan of the code wrote the feature's specification (a later scan that is queued, running, failed or dismissed does not change that). awaiting_review: a scan's draft is waiting for review, even when an earlier scan already wrote one. not_scanned: no scan has written one yet, which includes a first scan still queued or running, one that failed or was dismissed, and features no scan can read (domains, and features with no linked repository). A specification update proposed by a coding session is not a scan. The sub-feature listing does not apply it.
specificationProposalFilter by whether a SPECIFICATION PROPOSAL is pending. pending: the feature has a drafted rewrite of its specification waiting for review, or one approved in a pull request and not yet applied, from any source (a deep dive, a refresh, a composition, discovery, a coding session, review mode or a code chat). awaiting_review: only the drafts still waiting for someone to review them, from any source; an approved one waiting for its pull request is left out. in_progress: a run still queued or running, from any source (no draft exists yet). Not counted by any of them: an applied, dismissed or failed proposal, and a structure proposal (a proposed split, not a specification). pending and awaiting_review are wider than deepScan=awaiting_review, which counts only drafts from a scan of the code. The sub-feature listing does not apply it.
codePathFilter by a CODE PATH recorded on the feature's own application links: which features use this file or folder. A repository-relative path such as src/booking/booking.service.ts, or a folder ending in / such as src/booking/. By default the match is lenient, to find the owner of a file a scan may have recorded under a wrong or old folder: letter case is ignored, a recorded path matches when it is the same path, a folder holding it or a file inside the given folder, and, for a file, when the recorded FILE NAME contains the given file name, in any folder of any application (src/booking/booking.service.ts finds lib/legacy/booking.service.ts; booking.contr finds booking.controller.ts). A folder is never matched by name. Pass codePathExact=true to match only that exact path. Counted: the paths a scan recorded (less those a person hid), the paths added by hand, and the files entry points name. A feature matches through its own links, never a child's. Pass parentFeatureId=all to include sub-features: components are sub-features, and they carry most code paths. To map a change set (the files a diff touched) to features, use find-features-by-code-paths instead. The sub-feature listing does not apply it.
codePathExactWith codePath: true matches only that exact path, letter case included, with no folder containment and no file-name match. A leading ./, a trailing / and a #symbol suffix still name the same path. Defaults to false, the lenient match described on codePath. Ignored without codePath. The sub-feature listing does not apply it.
idsComma-separated feature UUIDs, at most 100: return only these features. Pass parentFeatureId=all to include sub-features. An id that no longer exists, or that the caller may not see, is simply absent from the answer. The sub-feature listing does not apply it.
includeDescriptionOpt in to receive each feature's full markdown description. Defaults to false: a catalog of fully-specified features runs to megabytes, past what a single tool call can return. Read the ones you need with get-feature instead.
List product features in a workspace › Responses
List of features
Create a product feature
Add a new feature to the product catalog. Features can be organized hierarchically using parentFeatureId. Titles at every level are short sentence-case noun phrases in the business's own vocabulary — see the title field. Status: backlog, planned, in_development, stable, deprecated.
path Parameters
workspaceIdWorkspace UUID
Create a product feature › Request Body
titleA short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.
parentFeatureIdkindcomponent for a unit that owns code and therefore owns business rules — a screen, a service module, a background worker, or the shared code a domain's capabilities have in common. feature for the business capability above it, whose description is composed from its components. domain ONLY for a named collection that organises features: it is purely organisational, owns no code, composes nothing and is never scanned. A person makes one; a catalogue scan makes one only when its instructions say the workspace's catalogue shape is domains, features and capabilities. In every other case a scan must never mint one, and when cataloguing you should treat every container as a feature. A child may not be broader than its parent (nothing above a component, no domain under a feature). When in doubt, ask whether a deep read of this row alone would have specific files to open — if not, it is a feature.
descriptionMarkdown, at most 200,000 characters.
priorityrequestingAccountIdrequestingContactIdownerIdAssign ONE user by UUID (legacy single-assignee field, historically the feature's 'owner'). Use assignees to assign several people or a team.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
estimatedEfforttargetDatesortOrderpositionWhere to place the feature among its siblings (same parent) when sortOrder is not supplied. end appends it below the last sibling, start puts it above the first. Ignored when an explicit sortOrder is given.
externalSourceexternalIdexternalSourceUrlCreate a product feature › Responses
Created feature
Which features own the files a change touched
The reverse of a feature's code surface. Pass the files you changed, per repository (git diff --name-only <base> plus untracked files, as repos[].paths; name each repository the way your environment lists it — the short name or the full owner/repo, both match). Returns the features whose RECORDED code surface covers them — the paths a scan attributed to the feature or a person added by hand — with, per feature and application, which surface entries matched, which of your files they covered, and whether the entry came from a scan (codePaths) or a person (manualCodePaths); most-covered first. unmatched lists your changed files no feature claims; unknownRepos the repositories no application here is attached to. A feature returned here is a CANDIDATE to check against your diff, not a verdict: a surface is a set of files, and a refactor inside one changes no observable behaviour. Read the candidate's specification (get-feature) and decide whether what a user can observe changed; if it did, propose the update with propose-feature-description.
path Parameters
workspaceIdWorkspace UUID
Which features own the files a change touched › Request Body
One entry per repository you changed. One call covers every repository.
Which features own the files a change touched › Responses
Candidate features, the changed files nothing claims, and the repositories nothing is attached to
Bulk create product features
Create multiple features at once (e.g., from Jira import). Maximum 200 features per request.
path Parameters
workspaceIdWorkspace UUID
Bulk create product features › Request Body
Bulk create product features › Responses
Created features
List sub-features of a parent feature
Returns child features nested under a parent feature in the hierarchy. Excludes the heavy Lexical CRDT payload and audit fields.
path Parameters
workspaceIdWorkspace UUID
idParent feature UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
parentFeatureIdParent feature UUID, or 'all' for all features
kindFilter by tier (single value or array). component returns only the code-owning leaves — the rows that carry business rules and that a component read scans; feature returns the business capabilities above them; domain returns only the hand-curated collections above THOSE, which own no code and are never scanned. feature does NOT include domains, so enumerating "everything above components" means passing both.
priorityFilter by priority (single value or array)
statusFilter by status (single value or array)
ownerIdFilter by assignee (historically 'owner'): a user or team UUID, or a comma-separated list of them (features assigned to ANY listed user/team match). my-teams stands for every team the caller belongs to, and for-me for the features FOR the caller: assigned to them, or in the area of a team they are on (assigned to the team or anywhere under a feature that is). for-me is the sidebar's Features counts.
teamIdFilter to a TEAM's area: a team UUID, or a comma-separated list of them (items in the area of ANY listed team match). my-teams stands for every team the caller belongs to. An item is in a team's area when it is assigned to the team, or sits under a feature assigned to it, at any depth: a feature's sub-features, their tasks and sub-tasks, the bug reports linked to those features and tasks, and the coding sessions working on them. Unlike assigneeId, which matches only items assigned directly. A user id matches nothing, and so does my-teams for a caller on no team. This list returns root features unless parentFeatureId is given: pass parentFeatureId=all for the team's whole area, sub-features included. The sub-feature listing does not apply it.
externalSourceFilter by externalSource marker (e.g. 'system_generated' to surface agent-suggested starter features).
tagsComma-separated tag names to filter by
applicationFilter by LINKED APPLICATION: a single application UUID, or a comma-separated list of them (features linked to ANY listed application match). The link is the feature's own depends_on → application edge — a parent whose CHILDREN are linked does not match. Top-level rows only; the sub-feature listing does not apply it.
codeSurfaceFilter by whether a CODE SURFACE is recorded on the feature's application links. recorded: at least one linked application carries code paths or entry points (from a scan or added by hand). missing: no linked application carries any — which includes features with no application link at all. Top-level rows only; the sub-feature listing does not apply it.
deepScanFilter by DEEP SCAN status (single value or array; a feature matching ANY listed value is returned). scanned: a scan of the code wrote the feature's specification (a later scan that is queued, running, failed or dismissed does not change that). awaiting_review: a scan's draft is waiting for review, even when an earlier scan already wrote one. not_scanned: no scan has written one yet, which includes a first scan still queued or running, one that failed or was dismissed, and features no scan can read (domains, and features with no linked repository). A specification update proposed by a coding session is not a scan. The sub-feature listing does not apply it.
specificationProposalFilter by whether a SPECIFICATION PROPOSAL is pending. pending: the feature has a drafted rewrite of its specification waiting for review, or one approved in a pull request and not yet applied, from any source (a deep dive, a refresh, a composition, discovery, a coding session, review mode or a code chat). awaiting_review: only the drafts still waiting for someone to review them, from any source; an approved one waiting for its pull request is left out. in_progress: a run still queued or running, from any source (no draft exists yet). Not counted by any of them: an applied, dismissed or failed proposal, and a structure proposal (a proposed split, not a specification). pending and awaiting_review are wider than deepScan=awaiting_review, which counts only drafts from a scan of the code. The sub-feature listing does not apply it.
codePathFilter by a CODE PATH recorded on the feature's own application links: which features use this file or folder. A repository-relative path such as src/booking/booking.service.ts, or a folder ending in / such as src/booking/. By default the match is lenient, to find the owner of a file a scan may have recorded under a wrong or old folder: letter case is ignored, a recorded path matches when it is the same path, a folder holding it or a file inside the given folder, and, for a file, when the recorded FILE NAME contains the given file name, in any folder of any application (src/booking/booking.service.ts finds lib/legacy/booking.service.ts; booking.contr finds booking.controller.ts). A folder is never matched by name. Pass codePathExact=true to match only that exact path. Counted: the paths a scan recorded (less those a person hid), the paths added by hand, and the files entry points name. A feature matches through its own links, never a child's. Pass parentFeatureId=all to include sub-features: components are sub-features, and they carry most code paths. To map a change set (the files a diff touched) to features, use find-features-by-code-paths instead. The sub-feature listing does not apply it.
codePathExactWith codePath: true matches only that exact path, letter case included, with no folder containment and no file-name match. A leading ./, a trailing / and a #symbol suffix still name the same path. Defaults to false, the lenient match described on codePath. Ignored without codePath. The sub-feature listing does not apply it.
idsComma-separated feature UUIDs, at most 100: return only these features. Pass parentFeatureId=all to include sub-features. An id that no longer exists, or that the caller may not see, is simply absent from the answer. The sub-feature listing does not apply it.
includeDescriptionOpt in to receive each feature's full markdown description. Defaults to false: a catalog of fully-specified features runs to megabytes, past what a single tool call can return. Read the ones you need with get-feature instead.
List sub-features of a parent feature › Responses
List of sub-features
Count what deleting a feature would remove
Counts what DELETE /features/{id} would remove with the feature: its sub-features at any depth, and the distinct tasks (subtasks included) linked to the feature or to any of them. Computed from the same closure the delete runs, and removes nothing. Returns counts only. Requires feature:delete.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Count what deleting a feature would remove › Responses
Sub-feature and task counts for a delete of this feature
Get feature requests promoted to this feature
Returns all feature requests that have been promoted to this feature via entity relationships.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Get feature requests promoted to this feature › Responses
List of promoted feature requests
Update feature status
Transition a feature between statuses: backlog, planned, in_development, stable, deprecated.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Update feature status › Request Body
statusUpdate feature status › Responses
Feature status updated
Move a feature under a different parent, or reorder it among its siblings
Re-parents a feature and positions it among its new siblings — the same operation as dragging a row in the Features tree. Pass a feature id as parentFeatureId to nest it, null to promote it to the top level, or omit the key to reorder within the current parent. The server re-indexes both the old and the new sibling lists, and rejects a move that would make a feature its own ancestor. The workspace feature map uses this to GROUP an existing flat catalogue under the domains it creates: move only features a scan created (never a row a person placed), never past the maximum hierarchy depth, and report every move in the run's movedFeatureIds. It changes placement only — never the title, description, status or links.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID (the feature being moved)
Move a feature under a different parent, or reorder it among its siblings › Request Body
sortOrderPosition among the new siblings, 0-based. The server re-indexes the rest of that sibling list around it, and re-indexes the old siblings too when the parent changes.
Where the feature lands: a feature id nests it under that parent, null promotes it to the top level, and omitting the key leaves the current parent alone. A move that would make a feature its own ancestor is rejected.
Move a feature under a different parent, or reorder it among its siblings › Responses
The moved feature
List logs on a feature
Returns log entries for a feature, newest first.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
List logs on a feature › Responses
List of logs
Add a log entry to a feature
Post a new log entry on a feature.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Add a log entry to a feature › Responses
Log added
Update a log entry on a feature
Edit your own log entry on a feature.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
logIdLog UUID
Update a log entry on a feature › Responses
Log updated
Get who can see and edit a feature
Returns the feature's access list: the teams that may see it and whether each may view or edit it, or, when the feature has no list of its own, the list it inherits from a private feature above it. A feature with no list anywhere above it is open to everyone in the workspace. Also returns what the caller may do with the feature.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Get who can see and edit a feature › Responses
The feature's access list
Get a feature by ID
Retrieve a single product feature with full details including hierarchy info, status, and linked feature requests. Pass ?includeLexical=true to also receive the Lexical CRDT payload (only the collaborative editor needs it).
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
query Parameters
includeLexicalOpt in to receive the Lexical CRDT payload alongside markdown. Defaults to false — only the collaborative editor needs it.
Get a feature by ID › Responses
Feature details
Update a product feature
Modify feature title, description, type, or priority.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Update a product feature › Request Body
kindcomponent for a unit that owns code and therefore owns business rules — a screen, a service module, a background worker, or the shared code a domain's capabilities have in common. feature for the business capability above it, whose description is composed from its components. domain ONLY for a named collection that organises features: it is purely organisational, owns no code, composes nothing and is never scanned. A person makes one; a catalogue scan makes one only when its instructions say the workspace's catalogue shape is domains, features and capabilities. In every other case a scan must never mint one, and when cataloguing you should treat every container as a feature. A child may not be broader than its parent (nothing above a component, no domain under a feature). When in doubt, ask whether a deep read of this row alone would have specific files to open — if not, it is a feature.
Which plane a COMPONENT's code sits in. Derived from the node's FILES by a catalogue run — do not guess it: leave the field out unless you are mirroring a scan's own classification or a human's explicit choice. Null clears it, which is correct for a container that owns no code and for any feature (a feature spans layers and carries no layer, ever).
titleA short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.
descriptionMarkdown, at most 200,000 characters. Replaces the whole description: send it only with the complete new text. To change part of the description, send descriptionEdits instead.
Change PART of the description without resending it: a list of exact find-and-replace edits the server applies to the stored description, in order, all or none. Each find must be copied exactly (same characters, spacing and line breaks) from the description as it stands, and must occur exactly once there at that point: include enough surrounding text to make it unique. replace is the new text (an empty string deletes the passage). Everything outside the passages is kept as it is. Prefer this over description for any change to a long description, and always when your read of the description was cut. Cannot be sent together with description.
prioritystatusSet the single USER assignee (legacy 'owner' field): replaces the feature's user assignees with this one, null unassigns every user. Team assignees are left untouched — use assignees to change them.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
sortOrderUpdate a product feature › Responses
Updated feature
Generate suggested tasks for a feature
Break a feature down into a suggested set of tasks using the AI task generator. The breakdown factors in the feature's title/description, its promoted feature requests (via PROMOTED_TO), the associated customer interests, and sibling features. Returns the suggested tasks WITHOUT creating them — the caller reviews the list and decides which to create (e.g. via create-task).
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Generate suggested tasks for a feature › Responses
Suggested tasks (empty array if generation failed)
Generate an AI description for a feature
Generate a template-structured description for a feature using the current title, description, and any linked feature requests (via PROMOTED_TO). Returns the generated markdown without persisting — the caller decides whether to apply it.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Generate an AI description for a feature › Responses
Generated feature description (description may be null if generation failed)
Find a feature by name or topic (combined lexical + semantic search)
Combines lexical and semantic search over features. Runs an indexed full-text search over every feature's title and whole description first: a match in the title ranks above a match in the description, and the best matches come first. Each hit carries match-highlighted snippets as plain-text segments (snippets[].segments[], each carrying match: true|false) for its title and for the opening of its description; a match further into a long description still finds the feature, without a body snippet. When the keyword query has no match and is longer than 5 characters, it falls back to semantic search over the knowledge base, so paraphrases still resolve (e.g. 'sign in flow' matches a feature titled 'Google SSO login'). Each result carries matchType: fulltext for the full-text path, semantic for knowledge-base fallback hits, whose scores are absolute semantic similarity, comparable across queries. Semantic hits below the server-side noise floor are filtered out, so an empty semantic fallback genuinely means no match.
path Parameters
workspaceIdWorkspace UUID
query Parameters
qSearch query
limitMax results (default 20, cap 50)
Find a feature by name or topic (combined lexical + semantic search) › Responses
Ranked feature matches with snippets and matchType
List version history for a feature document
Returns the version history of a feature document — every persisted snapshot, newest first. Use this to inspect prior wording, attribute changes to specific authors, or pick a version to restore.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
query Parameters
featureIdFeature UUID
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
searchFull-text search across searchable fields
List version history for a feature document › Responses
List of feature versions
Get a single feature document version
Fetch one historical version including its Lexical JSON state and the markdown projection. Useful for diff-rendering a snapshot or previewing before restore.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
versionIdVersion UUID
Get a single feature document version › Responses
Feature version detail
Name a feature document version
Attach (or clear) a human-readable summary to a version so it surfaces nicely in the history panel.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
versionIdVersion UUID
Name a feature document version › Responses
Renamed feature version
Restore a feature document to a historical version
Roll a feature document back to a prior version. Creates a new snapshot that mirrors the chosen version, writes it to the live feature, and broadcasts a doc:reset to any connected editors so they reload.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
versionIdVersion UUID
Restore a feature document to a historical version › Responses
Restored feature
List the KB documents linked to a feature
Returns the knowledge base documents that document this feature (kb_document documents feature), with hierarchy fields so callers can render them as a tree.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
List the KB documents linked to a feature › Responses
Linked KB documents
List the applications a feature depends on
Returns the applications linked to this feature (feature depends_on application). Each row carries the application id, display id (APP-N), name, repository name, and how much code surface the link records as two counts - codePathCount and entryPointCount, scan-recorded and hand-added together. The paths themselves are on get-feature-code-surface. For a monorepo application, services names the services of that application this feature lives in, as mapped by the architecture scan: source: folder when the feature's code paths sit inside the service's folder (matchedPath is the first one that does), source: manual when a person linked it by hand. An empty services means no service matched.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
List the applications a feature depends on › Responses
Linked applications
Link a feature to an application it depends on
Creates a feature depends_on application link (idempotent — re-linking an existing pair is a no-op) and records the CODE SURFACE for the pair: the files that implement the feature (codePaths), the entry points attributed to it (entryPoints) and a handover note (capabilityNotes). The per-feature deep dive opens exactly that surface first, so a repository map pass must call this once per feature it touches, with the full lists. Each key is merged individually — passing a key replaces the stored value, omitting it leaves the stored value untouched. Returns the MERGED surface as it now stands, which is the outcome of that merge and not what you sent: totals is exact, and it supersedes the surface you were handed at dispatch. Write every statement about which files this component owns from these numbers rather than from the manifest, and state them in your specification's Code surface receipt.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Link a feature to an application it depends on › Request Body
applicationIdcodePathsRepository-relative paths that implement this feature, most important first: entry-point files, service/domain logic, validators and guards, the constants holding literal values, the data model, UI surfaces and the tests that pin the behaviour. A directory is fine when the whole directory implements the capability; narrow a shared file with a symbol (src/routes/api.ts#createBooking). Five to forty entries is normal — src/ alone is worse than useless. Passing this key REPLACES the stored list; omitting it leaves the stored list untouched.
entryPointsExactly the entry points attributed to this feature, one per array entry, each as "POST /bookings — src/booking/booking.routes.ts:42, cron: reap-previews — src/jobs/reaper.ts:18). A path is not an entry point: the deep dive checks that every entry point listed here appears as its own contract block in the spec it writes. Passing this key REPLACES the stored list.
layerWhich layer this feature occupies IN THIS application — frontend, backend, data or external. Set by the workspace feature map, which is the only pass that sees several repositories at once and can therefore say a feature starts in a web app and ends in a database. Passing this key REPLACES the stored value; omitting it leaves it untouched, so a plain UI link can never blank it.
capabilityNotesOne to three sentences the deep-dive agent reads before it starts: whether this is a domain parent and which cross-cutting concerns it owns, where the rule-dense code is, which feature it is easily confused with, and anything surprising noticed but not pursued. A handover note, not a summary — do not repeat the description here.
Link a feature to an application it depends on › Responses
The merged code surface as it now stands, with exact totals
Unlink a feature from an application
Removes the feature depends_on application link. Returns the updated list of linked applications.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
applicationIdApplication UUID
Unlink a feature from an application › Responses
Updated linked applications
Set the hand-added half of a link's code surface
Writes the HUMAN-owned lists on one feature<->application link - manualCodePaths and manualEntryPoints, hiddenCodePaths (paths a scan recorded that a person replaced with a corrected one), and the link's services: manualSystemComponentIds (services of this application linked by hand) and hiddenSystemComponentIds (services matched by folder that a person hid). A key that is present replaces the stored list (send the whole edited list; remove an entry by omitting it); a key that is absent is left untouched. Kept apart from the scan's codePaths / entryPoints (link-feature-application) under keys no scan writes, so a hand-added entry, and a correction, survives every rescan. Every reader - the deep read, the spec audit, the reverse lookup, the rail - sees the union, and none of them sees a hidden path. To correct a path a scan recorded, add the corrected path to manualCodePaths and the old one to hiddenCodePaths in one request. Whenever either code-path list is sent, hiddenCodePaths keeps only the paths the scan's own list still holds and that are not on manualCodePaths, so adding a hidden path back by hand brings it back. Entries are trimmed, a leading ./ or / stripped, duplicates dropped, and the lists capped like the scan's. A service id you add must be a service of this application, or the request is refused with 400; adding a service by hand also un-hides it, and an id whose service no longer exists is dropped. A rewrite of the list already stored is a no-op. Returns the link's whole surface as it now stands, with its services and the application's services to choose from.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
applicationIdApplication UUID
Set the hand-added half of a link's code surface › Request Body
manualCodePathsmanualEntryPointshiddenCodePathsmanualSystemComponentIdshiddenSystemComponentIdsSet the hand-added half of a link's code surface › Responses
The link's code surface as it now stands — scan ∪ manual, with the manual lists beside it
List a feature's dependency edges, both directions
Returns every feature-to-feature dependency edge touching this feature: direction "uses" rows are features this one builds on, "used_by" rows are features that build on this one. Each row carries the other feature (id, COMP-N/FEAT-N, title, kind, status) plus the recorded rationale and file:line evidence.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
List a feature's dependency edges, both directions › Responses
Dependency edges
Record that this feature depends on another feature
Creates a directed feature uses feature edge: this feature calls the target's API, consumes a queue it fills, or reads data it owns. Mutual coupling is two calls, one per direction. Idempotent — re-linking an existing pair merges the new rationale/evidence onto the stored edge instead of duplicating it. Never link a parent to its own child (the hierarchy already carries that), and never record 'both touch the same repository' trivia: an edge needs a mechanism. A feature holds at most 12 outgoing edges; past that the call is rejected and the coupling belongs on the parent feature. Returns the updated edge list.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID (the feature that USES the target)
Record that this feature depends on another feature › Request Body
targetFeatureIdThe feature this one builds on — the direction is <this feature> uses <target>: it calls the target's API, consumes a queue the target fills, or reads data the target owns. Mutual coupling is two separate calls, one in each direction. Linking an already-linked pair is safe and REPLACES the stored rationale/evidence.
rationaleOne sentence naming the MECHANISM of the dependency ("reads the bookings table BookingLedger owns", "calls POST /payments on checkout") — never a restatement that the two are related. Rendered to humans curating the map.
evidenceCode locations proving the edge, each as "
Record that this feature depends on another feature › Responses
Updated dependency edges
Remove a feature dependency edge
Removes the feature uses feature edge. Returns the updated edge list.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID (the edge's source)
targetFeatureIdFeature UUID (the edge's target)
Remove a feature dependency edge › Responses
Updated dependency edges
List a component's business rules, or roll them up over a feature
Returns business rules as rows, ordered for reading. Each carries the rule text, the literal values it compares against, where it is enforced, what happens when it is broken, the verbatim evidence quote and the code citations behind it. A feature owns no rules directly — its components do, so pass ?rollUp=true on a feature to get the union over every component beneath it, each row naming the component it came from. On a component, the default is its own applied set. ?proposalId= reads the rows a legacy markdown proposal parsed (which may not be applied yet) and ?batchId= reads one submit wave.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
query Parameters
proposalId^([0-9a-fA-F]{8}-[0-…Return the rules parsed for this description proposal (the review overlay's case — rows that may not be current yet). Omit for the feature's current applied rule set.
batchId^([0-9a-fA-F]{8}-[0-…Return one submit wave's rules, promoted or not. Omit for the current applied set.
rollUpReturn the applied rules of this feature's component descendants instead of its own. This is how a feature answers 'what are my business rules' — a feature owns none directly; its components do. Each row carries the component it belongs to.
List a component's business rules, or roll them up over a feature › Responses
Business rules, ordered by component then reading order
Write a wave of business rules against a component
Records business rules on a component — the code-owning leaf of the feature tree. Call it repeatedly as you write, a wave at a time, with the same batchId; check each wave's evidence while the files you cited are still open, and set final: true on the last one to make the whole batch the component's applied rule set. Waves are cumulative and re-sending a batch replaces it, so a lost response is safe to retry. This replaces writing rules into a specification's ## Business Rules section: a document is capped at 200,000 characters and one message at 64,000 output tokens, and rules were half of it. Rejected on a feature — submit against the component whose code enforces the rule, and the feature's roll-up picks it up.
path Parameters
workspaceIdWorkspace UUID
idComponent feature UUID
Write a wave of business rules against a component › Request Body
batchId^([0-9a-fA-F]{8}-[0-… · requiredA UUID you mint for this submit wave and reuse on a retry. Re-sending the same batch replaces it rather than doubling it, which is what makes a lost response safe to repeat.
Up to 40 rules. Submit in waves as you write them, checking each wave's evidence while the files are still open, rather than accumulating the whole set for one call.
sessionId^([0-9a-fA-F]{8}-[0-…The scan session producing these rules, when there is one.
proposalId^([0-9a-fA-F]{8}-[0-…The description proposal these rules accompany, when there is one.
finalTrue on the last wave. Promotes every wave of this batch to the component's applied rule set in one step, so a partial submit never half-replaces what is live.
Write a wave of business rules against a component › Responses
What the wave wrote, and whether the batch was promoted
Make a submitted batch the component's applied rule set
Promotes one batchId to the component's applied rules, replacing the previous applied set written by the same kind of writer. Only needed when a run submitted its waves without final: true — the ordinary path promotes on the last wave.
path Parameters
workspaceIdWorkspace UUID
idComponent feature UUID
Make a submitted batch the component's applied rule set › Request Body
batchId^([0-9a-fA-F]{8}-[0-… · requiredThe batch to make this component's applied rule set.
Make a submitted batch the component's applied rule set › Responses
How many rules became current
Scan the feature's linked application repos and propose an updated description
Starts a background Productmind agent scan of every application repository linked to this feature. The agent surfaces the business/product logic in the code into a proposed replacement description, submitted as a FeatureDescriptionProposal the user reviews as a block diff before anything lands. Delta-aware: repos carry the last-scanned commit so subsequent scans focus on what changed. What is dispatched depends on the tier: a component, or a feature with no components, is read as one document and the queued proposal is returned; a feature that HAS components is never read as one document - a component read is started for each descendant that needs one and proposal comes back null. The parent's own specification is composed from them afterwards: call this again once nothing is left to read (it then composes and returns the composition proposal), or call compose-feature-description, which also composes around components that have no specification. The composition is not started automatically when the components finish. Returns 202 either way.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Scan the feature's linked application repos and propose an updated description › Responses
What the call dispatched — either a queued proposal (which doubles as the scan run tracker) or the components it fanned out to
Compose the feature's specification from its components
Starts a background Productmind agent run that writes this feature's specification from its components' specifications and business rules, without reading any code. Components with no specification yet (never read, or their read failed) are named as gaps in the result rather than blocking it, and are returned in skippedComponents, but at least one component must have something to compose from: when none has a specification or a business rule yet, the request is refused (refresh the feature to read its components first). Only a feature with components can be composed; refresh a feature without components to read its code instead. Refused while any component is still being read, and while another description proposal is in progress for this feature. Uses AI credits (one user-hosted session when it runs on your own machine); a billing refusal is returned as that error (402 or 429). Returns 202 with the queued composition proposal.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Compose the feature's specification from its components › Responses
The queued composition proposal (it doubles as the run tracker; failed when the dispatch could not start for a reason other than billing) and the components composed around as gaps
Revise the feature's specification from its open review comments
Sends the open comments on passages of this feature or component document to a background Productmind agent, which reads each comment and the code it concerns in the linked application repositories (for a feature composed from components, theirs), revises only the passages the comments point at, replies in every thread, and submits the result as a description proposal that is reviewed block by block before anything changes. The agent never resolves a thread: applying the proposal resolves the threads it was sent, and dismissing it leaves them open. At most the 50 oldest open threads are sent. Refused for a domain, when no linked application has a repository, when the document has no open comments, and while another description proposal is in progress for this feature. Uses AI credits (one user-hosted session when it runs on your own machine); a billing refusal is returned as that error (402 or 429), and nothing is started when no agent can run it. Returns 202 with the queued proposal.
path Parameters
workspaceIdWorkspace UUID
idFeature or component UUID
Revise the feature's specification from its open review comments › Responses
The queued review proposal, which doubles as the run tracker
The files and entry points a scan recorded for this feature
Returns one entry per linked application carrying the code surface recorded on that link: codePaths (repository-relative paths that implement the feature), entryPoints ("<kind> <identifier> — <path:line>") and capabilityNotes. Both lists are the UNION of what the last scan recorded and what people added by hand, less the scan paths a person replaced; manualCodePaths / manualEntryPoints beside them are the hand-added lists as stored, and hiddenCodePaths the replaced paths as stored, which set-feature-application-surface edits and no scan ever touches. This is the same handover a per-feature deep read is scoped by, and it exists for EVERY catalogued node — including the capabilities the deterministic graph attaches no decision slice to. Empty arrays for a link made by hand with nothing added yet, or predating the two-phase discovery split; an application with no repository is listed with repoName null.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
The files and entry points a scan recorded for this feature › Responses
One recorded code surface per linked application
How the feature's linked repos compare to their last scan baselines
Counts the commits on each linked application repo's base branch since that link's last-scanned commit (via the git provider's compare API). Drives the feature doc's Refresh control: new_commits shows the 'N new commits' pill, up_to_date disables the button, unknown (never scanned / provider error / service auth) keeps it enabled with no notice. Results are cached ~60s per repo+baseline.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
How the feature's linked repos compare to their last scan baselines › Responses
Aggregate freshness plus one entry per linked application
List description proposals for a feature
Returns the feature's scan-driven description proposals, newest first. Pass ?activeOnly=true for the single in-flight proposal (queued/running/awaiting_review), if any — the feature document page polls this to drive the refresh control.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
query Parameters
statusFilter by status
activeOnlyOnly the active proposal, if any
List description proposals for a feature › Responses
Description proposals
Propose an updated description for an existing feature
Submit a FULL replacement markdown description for an existing feature as a reviewable proposal. This REPLACES update-feature for every scan-driven description change: the proposal is shown to a human as a block-by-block diff (accept/reject per block) and only lands after they apply it - EXCEPT a deep-dive proposal (a feature the repository map pass just created, whose description is still the untouched one-paragraph stub), which applies immediately; a user edit mid-scan drops it back to human review. Pass the scan session id (from your Session context) as sessionId so the proposal is bound to your run. Returns 409 when a proposal is already pending for the feature - skip it and note the conflict in your final report. CALL THIS ONCE. The reply is a receipt, not the document, and any auditResult findings on it are ADVISORY - they are recorded for the reviewer and never block, so a finding is not a reason to submit again: submitting a corrected document over one that already landed does not replace it, it opens a SECOND proposal that parks the applied work behind review and takes the feature's only proposal slot. Retry only a call that failed to land (transport error, timeout, 5xx). If the Productmind agent's productmind-mcp server is available, prefer its submit_feature_spec, which sends the document from a file instead of re-typing it. From a CODING session, call this in the pre-PR documentation turn when the change altered what a user can observe (find the candidates with find-features-by-code-paths): the proposal is reviewed in the session's PR rail beside the documentation proposals and lands when the pull request merges.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
Propose an updated description for an existing feature › Request Body
proposedDescriptionMarkdownThe FULL replacement description markdown for the feature. Code citations are link tokens — path/to/file.ext:line @
summaryOne-paragraph summary of what changed and why
sessionIdThe scan session id (from the Context section of your instructions)
REQUIRED by the deep-read instructions: either the Knowledge Base document ids you created for this feature's technical architecture (API contracts, data layers, databases, queues, execution models, state managers), or an explicit reason none was needed.
commentIdWhen you answer a comment thread on this feature's document (your turn input names it): the thread's id, exactly as given. The suggestion is then linked to the thread, and applying it resolves the thread. Only the thread you were asked to answer, while you answer it; omit it otherwise.
Propose an updated description for an existing feature › Responses
Receipt for the submitted proposal — status, whether it applied, and any advisory audit findings. It deliberately does NOT echo the description back: you just sent it, and on a second submit the echo (which carries the previously applied text as well) grows past what a tool result can carry.
Apply a reviewed description proposal
Writes the user-composed markdown (accepted diff blocks applied onto the current description) to the feature via the standard versioned update path (a restorable FeatureVersion snapshot is taken first), broadcasts doc:reset to connected editors, marks the proposal applied, and stamps the scanned commits onto the feature↔application links as the next scan's delta baseline.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
proposalIdProposal UUID
Apply a reviewed description proposal › Request Body
descriptiondraftVersionApply a reviewed description proposal › Responses
Applied proposal
Approve a session's description proposal without applying it
The PR-rail review of a session proposal: freezes the user-composed markdown (accepted diff blocks applied onto the current description) as approvedDescriptionMarkdown and re-freezes the base to the live description, so the PR-merge webhook writes exactly what was approved and can veto on drift. Does NOT write the feature — that happens when the pull request merges (or on the feature page, where apply accepts an approved proposal). Only an awaiting_review proposal from a coding session can be approved.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
proposalIdProposal UUID
Approve a session's description proposal without applying it › Request Body
descriptiondraftVersionApprove a session's description proposal without applying it › Responses
Approved proposal
Dismiss a description proposal
Rejects the proposal wholesale. The scan baseline on the feature↔application links is NOT advanced, so the next refresh re-scans from the last applied baseline.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
proposalIdProposal UUID
Dismiss a description proposal › Responses
Dismissed proposal
Cancel an in-flight description scan
Stops a queued/running refresh scan: settles the proposal (failed/'Cancelled', releasing the one-active-per-feature slot) and best-effort cancels the backing scan session so the agent stops. A proposal already awaiting review cannot be cancelled - dismiss it instead. The scan baseline is never advanced. Only the person who started the scan, or someone who manages the workspace (an organization Owner or Admin, the workspace's owner or one of its admins), can stop it.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
proposalIdProposal UUID
Cancel an in-flight description scan › Responses
Cancelled proposal
Propose splitting a flat feature into a parent + subfeatures (human-reviewed)
Use this (instead of create-feature / propose-feature-description) when an EXISTING flat feature should become a high-level domain PARENT with new detailed subfeatures — e.g. turning one 'Finance — payment ledger & invoicing' feature into a 'Finance' parent with 'Payment ledger' and 'Invoicing' children. Optionally retitle/redescribe THIS feature as the parent (parentTitle/parentDescriptionMarkdown), list the ordered NEW children, and/or re-parent THIS feature under an existing one (moveUnderParentId). A human reviews the proposed split before anything is created/re-parented. Pass your scan session id as sessionId. Returns 409 when a proposal is already pending for the feature — skip it and note the conflict. Only propose a split for a feature that has NO existing children.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID (the subject that becomes the parent)
Propose splitting a flat feature into a parent + subfeatures (human-reviewed) › Request Body
parentTitleNew title for THIS feature, retitled as a high-level domain parent (e.g. 'Finance'). Omit to keep the current title. A short sentence-case noun phrase in the vocabulary a product manager and a developer both use unchanged — the domain concept, plus the operation nominalised onto it where the concept alone does not name the capability. Password reset, not Resetting a forgotten password; Customer management, not Managing customers and not a bare Customer. No articles, possessives or imperatives, and no implementation words (service, handler, worker, API) unless the product's own user-facing wording uses them. The same register at every level: a parent names a broader concept, not a different kind of word.
parentDescriptionMarkdownNew HIGH-LEVEL description for THIS feature as the domain parent — what the domain does and the sub-capabilities it contains. Omit to keep the current description.
Ordered NEW subfeatures to create under this feature, each with its own full detailed spec.
Optionally re-parent THIS feature. Pass an existing feature id to move it under that parent, or null to promote it to a ROOT feature (use this for a domain wrongly filed under an era/technology bucket). Omit the key entirely to leave it where it is — null and omitted mean different things.
summaryOne-paragraph summary of the proposed restructure and why.
sessionIdThe scan session id (from the Context section of your instructions).
Propose splitting a flat feature into a parent + subfeatures (human-reviewed) › Responses
Structure proposal awaiting review
Apply a reviewed structure proposal
Performs the reviewer-edited restructure atomically: snapshots + retitles/redescribes the subject feature (broadcasting doc:reset to connected editors, with a restorable FeatureVersion), creates the ordered new children under it, optionally re-parents it, links the new children to the scanned application, and marks the proposal applied. Note: one-click restore of the 'Before restructure' version reverts only the subject's DESCRIPTION — restoreVersion never reassigns the title, and it does not remove the created children.
path Parameters
workspaceIdWorkspace UUID
idFeature UUID
proposalIdProposal UUID
Apply a reviewed structure proposal › Request Body
parentTitleparentDescriptionMarkdownApply a reviewed structure proposal › Responses
Applied structure proposal