Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-06 23:20:53 +01:00
Code Issues Packages Projects Releases Wiki Activity

Reconcile Claude platform packages with merged Codex defaults

Browse Source 
Co-Authored-By: Paperclip <noreply@paperclip.ing>

* codex/claude-runner-default: (85 commits)
  feat: default new Codex agents to Paperclip Runner on Linux and macOS (#15683)
  docs(skills): add slow-query diagnosis and fix skill (#16303)
  feat(sentry): add opt-in run failure reporting with saved run references (#16300)
  refactor(server): isolate provider message admission and runtime policies (#16289)
  refactor(server): isolate provider webhook lifecycle decisions (#16283)
  fix(workspaces): keep cleanup Git scans fresh and dedupe page reads (#16302)
  fix(sentry): keep provider-rejected Grok wakes out of run failure reports (#16297)
  fix(runner): report Runner disconnect age when a Dot bridge exits (#16296)
  refactor(server): isolate chat conversation and control policies (#16276)
  perf(recovery): use indexed execution identity lookups (#16291)
  perf(runs): bound history and reduce repeated context reads (#16286)
  fix(native-runtime): report which close barrier failed (#16298)
  feat(skills): select and validate tracked GitHub branches (#16288)
  fix(observability): sample native runs independently of triggers (#16285)
  fix(github): retry and recover review publication (#16284)
  perf(workspaces): wake terminal cleanup from committed changes (#16282)
  fix(mcp): deduplicate discovered tool descriptors (#16281)
  perf: remove history scans from task and chat queries (#16278)
  docs(skills): add maintenance bot setup workflow (#16279)
  fix(observability): time execution configuration steps (#16236)
  ...

# Conflicts:
#	scripts/verify-grok-npm-install.mjs
This commit is contained in:
Dotta committed 2026-10-14 12:12:58 -05:00
2 parents e3bf43e216 28a02f1853
commit b030683ca2
1176 files changed
+129461 -261897
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

maps/feature-map/README.md
+36 -106
View File
@@ -9,92 +9,16 @@ The sibling [agent access map](../agent-access-map/README.md) records APIs,
agent entry points and permission boundaries for the same capability IDs.
Follow the [shared map contract](../README.md) when maintaining either map.
## Features
## Browse features
The map is organized by user capability, not by source file. It covers **35 feature
families** across the product, CLI, and operator workflows, checked against source
on 2026-10-12. Experimental and developer-only surfaces are labeled explicitly.
Each recipe includes sub-features, current entry points, automated evidence,
manual verification steps, and gotchas.
Open the [published Storybook guide](https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/?path=/story/overview-storybook-guide--coverage-guide)
for the assembled feature and capability index. The Markdown recipes in this
directory are the authored source. Each has a same-named agent-access companion.
### Getting started and access
| Feature | What it covers |
| --- | --- |
| [Onboarding and first work](./onboarding.md) | Instance setup, company wizard, first agent and task. |
| [Login, invitations, and access](./access.md) | Sessions, bootstrap, membership, roles, and CLI authorization. |
| [Companies and portability](./companies.md) | Company switching/settings, archival, package import/export. |
### Tasks and conversations
| Feature | What it covers |
| --- | --- |
| [Task creation and lifecycle](./tasks.md) | Creation, assignment, lists, properties, comments, and completion. |
| [Delegation, dependencies, and signoff](./task-coordination.md) | Child work, prerequisites, reviewers, and task-tree controls. |
| [Inbox, decisions, and search](./inbox-search.md) | Personal triage, decision queues, unread/blocked views, and search. |
| [Agent conversations and project handoff](./agent-chat.md) | Persistent conversations, discovery, handoff, and gated board chat. |
| [Questions and approvals](./questions-and-approvals.md) | Question/plan responses, formal approvals, and app-tool review. |
| [Steering and queued messages](./steering.md) | Follow-ups, queue edits, interruption, and pause/resume. |
| [Documents, attachments, and work products](./documents-artifacts.md) | Versioned documents, annotations, files, outputs, and artifact library. |
### Agents and reusable capabilities
| Feature | What it covers |
| --- | --- |
| [Hiring, configuration, and organization](./agents.md) | Agent identity, instructions, reporting lines, lifecycle, and built-ins. |
| [Runs, harnesses, and model accounts](./runs-adapters.md) | Adapter/model setup, account validation, transcripts, and run history. |
| [Skills and Skill Studio](./skills.md) | Discovery, sources, authoring, revisions, tests, and agent policies. |
| [Team packages and installation](./teams.md) | Catalog preview/install via CLI/API; catalog UI availability called out. |
### Projects and execution
| Feature | What it covers |
| --- | --- |
| [Projects and repositories](./projects.md) | Project lifecycle, task context, repository configuration, and defaults. |
| [Goals and work alignment](./goals.md) | Goal hierarchy, ownership, status, and project/task context. |
| [Workspaces, services, and files](./workspaces.md) | Provisioning, task bindings, services/logs, Git/files, and closure. |
| [Execution environments](./execution-environments.md) | Local, SSH, sandbox providers, target probes, and custom images. |
| [Recovery](./recovery.md) | Stopped work, workspace repair, bounded continuation, and reconnect. |
### Apps, channels, and extensions
| Feature | What it covers |
| --- | --- |
| [Connection setup](./connection-setup.md) | Catalog, MCP links, task requests, authentication, and setup resumption. |
| [App access and action permissions](./app-permissions.md) | Agent grants, off/ask/allowed actions, discovery, tests, and revocation. |
| [External chat and email](./chat-channels.md) | Provider-specific identity, threads, files, delivery, and endpoint upkeep. |
| [Tool gateways and access profiles](./gateways-profiles.md) | Tool exposure, client configuration, tokens, profiles, and activity. |
| [Secrets and proposals](./secrets.md) | Company/user credentials, grants, proposals, and vault import. |
| [Plugins](./plugins.md) | Installation/configuration, contributed pages/tools, and lifecycle. |
### Automation and structured work
| Feature | What it covers |
| --- | --- |
| [Routines, schedules, and triggers](./routines.md) | Definitions, variables, scheduled/webhook/manual runs, and history. |
| [Pipelines, review queues, and learnings](./pipelines.md) | Experimental stages, automation, items, review, and learning records. |
| [Cases](./cases.md) | Experimental structured fields, relationships, revisions, and task links. |
| [Status cards](./status-cards.md) | Experimental summaries, watched work, refresh history, and settings. |
### Oversight and operation
| Feature | What it covers |
| --- | --- |
| [Costs and budgets](./budgets-costs.md) | Spend reports, scoped limits, incidents, hard stops, and resumption. |
| [Dashboards and audit trails](./activity.md) | Company health, live work, activity, runs, routines, and timeline. |
| [Navigation, profile, and announcements](./navigation-preferences.md) | Sidebar state, favorites/recents, personal identity, and dismissals. |
| [Instance operations](./instance-operations.md) | Installation, updates, service health, configuration, and backups. |
| [CLI/API and local worktrees](./cli-operations.md) | Explicit context, resource commands, outputs, runs, and isolated instances. |
### Contributor surfaces
| Feature | What it covers |
| --- | --- |
| [Developer previews and diagnostic labs](./developer-labs.md) | Design examples, interaction fixtures, performance checks; not production acceptance. |
These are verification instructions, not a claim that every journey passed a live
test. A component test proves its component; a scripted provider proves that
fixture integration. Record executed results separately from the map.
Run `node scripts/storybook-catalog.mjs` to generate local navigation in
`maps/generated/feature-map.md`, `maps/generated/agent-access-map.md`, and the
Storybook guide. A new recipe is discovered automatically; do not register it in
this README or maintain counts here.
## Before driving a journey
@@ -142,40 +66,46 @@ For Paperclip-assigned work, attach evidence through the
## Inventory and remaining depth
[The UI coverage inventory](./coverage.json) accounts for every non-test TSX
module under `ui/src/pages`, including supporting panels, legacy variants, and
labs. Every product area now links to concrete recipes. **Partial** means the
area still has the named variant or workflow gaps; **unmapped** is reserved for
an area with no recipe. These statuses describe documentation, not runtime health.
The page inventory is a source snapshot dated 2026-10-05. The map also
includes entry points hosted inside other modules (pipeline Review Queue and
Learnings, task documents, onboarding), CLI-only operations, and operator work.
The team recipe explicitly distinguishes the current CLI/API path from catalog
UI components without a current top-level route. Refer to [route registration](../../ui/src/App.tsx)
and the [CLI registry](../../cli/src/index.ts) when changing reachability.
Remaining depth includes complete provider/auth/attachment matrices, every
harness/model/environment capability combination, third-party plugin features,
and every role/error/mobile/legacy-shell permutation. The recipes name relevant
gaps instead of equating source presence with a working user journey. The index
can include capabilities that do not add a page file.
The generated `maps/generated/coverage.json` lists the current non-test TSX page
modules and the recipes that directly reference each one. An unreferenced module
is a documentation candidate, not proof that its feature is absent or untested.
Remaining workflow limits live in each recipe. Inventory and example associations
describe documentation scope, not runtime health.
## Maintaining the reference
The map documents user journeys. It does not execute them automatically;
`coverage.json` records documentation scope rather than live test health.
generated inventories record documentation scope rather than live test health.
When maintaining a recipe, compare its entry points and expected results with
the current source. Check that linked tests still exercise the stated behavior
and that local references still exist. Refresh the inventory snapshot when it
helps explain the current product. Keep the same-named agent access companion
and that local references still exist. Keep the same-named agent access companion
and stable sub-feature IDs aligned when behavior or access changes. Source-only
access inventory remains distinct from live verification. Run
`node scripts/check-maps.mjs` after map edits for structural/reference checks;
follow the shared contract for the source and behavioral checks it cannot perform.
Each recipe starts with an H1 and a user-visible description, then exactly:
Each recipe starts with a small frontmatter navigation record, then an H1:
```markdown
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":10}
---
```
The H1 supplies the feature title, and the first paragraph supplies its summary.
Orders are local to the section; leave gaps for additions. Equal orders use the
stable filename as a tie-breaker. Keep a section's name/order consistent across
its recipes. A new feature or capability needs only its recipe and companion.
Optional `### Storybook verification` guidance lives inside the recipe's Gotchas
section. Each level-four heading contains a backtick-quoted capability key and
has `Scope` (`ui`, `cli`, or `browser`),
`Storybook`, `Production`, and `Sources` fields. These are verification instructions
and intentional scope limits, not run results or a required story for every API.
The generated gap report combines this guidance with current story associations.
After frontmatter, each recipe starts with an H1 and a user-visible description, then exactly:
1. **Sub-features** — stable backticked IDs and observable behavior/states.
2. **How to get to it (user POV)** — one H3 backticked entry-point ID per surface.
maps/feature-map/access.md
+27
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Getting started and access","sectionOrder":10,"order":20}
---
# Login, invitations, and access
People and agents enter the correct instance and company with the permissions granted to their identity. Login, membership, resource access, and CLI authorization have separate controls.
@@ -62,3 +66,26 @@ logout alone does not establish that server revocation succeeded.
- Settings visibility is not authorization; direct requests still need permission checks.
- An agent bearer key must not gain another company’s access.
- Never put invite tokens, session cookies, or API keys in verification evidence.
### Storybook verification
#### `login`
Scope: ui
Storybook: Sign-in form, pending and invalid credentials, deployment-mode claim gate, expired claim.
Production: Authenticate and reload company deep link; sign out and confirm session enforcement; reject invalid bootstrap claim.
Sources: Source: [Auth.tsx](../../ui/src/pages/Auth.tsx), [BoardClaim.tsx](../../ui/src/pages/BoardClaim.tsx), [board-claim.ts](../../server/src/board-claim.ts). Tests: [Auth.test.tsx](../../ui/src/pages/Auth.test.tsx), [auth-session-route.test.ts](../../server/src/__tests__/auth-session-route.test.ts), [board-claim.test.ts](../../server/src/__tests__/board-claim.test.ts)
#### `membership`
Scope: ui
Storybook: Member and join-request lists; editable versus read-only roles; pending change, rejected request, revoked invite.
Production: Persist role/membership changes; enforce actual actor authority, invite replay/expiry and cross-company denial.
Sources: Source: [CompanyAccess.tsx](../../ui/src/pages/CompanyAccess.tsx), [authz.ts](../../server/src/routes/authz.ts). Tests: [CompanyAccess.test.tsx](../../ui/src/pages/CompanyAccess.test.tsx), [invite-accept-replay.test.ts](../../server/src/__tests__/invite-accept-replay.test.ts), [multi-user-authenticated.spec.ts](../../tests/e2e/multi-user-authenticated.spec.ts)
#### `cli-auth`
Scope: ui
Storybook: CLI authorization approval, pending, expired/denied and already-authorized states.
Production: Authorize intended CLI identity/context, make scoped request, revoke current server token and retry same bearer; logout alone is insufficient.
Sources: Source: [CliAuth.tsx](../../ui/src/pages/CliAuth.tsx). Tests: [cli-auth-routes.test.ts](../../server/src/__tests__/cli-auth-routes.test.ts), [board-auth.test.ts](../../cli/src/__tests__/board-auth.test.ts), [token.test.ts](../../cli/src/__tests__/token.test.ts)
maps/feature-map/activity.md
+18 -1
View File
@@ -1,4 +1,8 @@
# Dashboards, activity, and audit trails
---
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":20}
---
# Dashboards and audit trails
People inspect company health, recent activity, run history, and routine activity, then follow evidence back to the task or agent responsible.
@@ -56,3 +60,16 @@ the routine rather than treating that component test as a reachable journey.
- Audit/activity events, run-log rows, first-party Telemetry, and operator OpenTelemetry traces are separate data paths.
- A healthy stream or dashboard counter alone does not prove task success.
- Cost and budget reports have their own [recipe](./budgets-costs.md).
### Storybook verification
#### `runs`
Scope: ui
Storybook: Mount AuditRuns selected status/agent/routine, linked task/agent, empty/loading/error/retry and 200-entry limit. Do not invent pagination.
Production: GET /companies/{id}/heartbeat-runs and /routines/{id}/runs require company/read/privacy checks; real browser follows context links and confirms the referenced execution.
Company run history defaults to 200 rows and caps explicit limits at 1,000.
Summary contexts omit stored prompts and expand JSON once per returned row.
The array response and run visibility/redaction checks remain in place.
Agent detail links resolve older runs by ID outside the recent history page.
Sources: Source: [AuditRuns.tsx](../../ui/src/pages/audit/AuditRuns.tsx), [heartbeats.ts](../../ui/src/api/heartbeats.ts), [routines.ts](../../ui/src/api/routines.ts). Tests: [AuditRuns.test.tsx](../../ui/src/pages/audit/AuditRuns.test.tsx), [heartbeat-run-privacy-routes.test.ts](../../server/src/__tests__/heartbeat-run-privacy-routes.test.ts), [routines-service.test.ts](../../server/src/__tests__/routines-service.test.ts)
maps/feature-map/agent-chat.md
+13
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":40}
---
# Agent conversations and project handoff
A person can hold a persistent conversation with an agent, return to its history, and hand useful work into a project or task. The gated conference-room chat is a separate conversation surface.
@@ -61,3 +65,12 @@ Manual: Check disabled access first, enable in the disposable instance, then sen
- Idle chat is not failed execution.
- See [steering](./steering.md) for in-flight messages and [questions](./questions-and-approvals.md) for interactions.
- An API tool test does not prove that every harness will choose the same handoff tool.
### Storybook verification
#### `conference-room`
Scope: ui
Storybook: Conference-room flag disabled, empty/history/reply, busy and explicit failure states.
Production: Exercise separate BoardChat route gate, local-trusted deployment and authenticated Claude CLI; send/reload real conversation with responding agent attribution.
Sources: Source: [BoardChat.tsx](../../ui/src/pages/BoardChat.tsx), [board-chat.ts](../../server/src/routes/board-chat.ts). Tests: [BoardChat.test.tsx](../../ui/src/pages/BoardChat.test.tsx), [board-chat-route-feature-flag.test.ts](../../server/src/__tests__/board-chat-route-feature-flag.test.ts)
maps/feature-map/agents.md
+38 -1
View File
@@ -1,4 +1,8 @@
# Hiring, agent configuration, and organization
---
navigation: {"section":"Agents and reusable capabilities","sectionOrder":30,"order":10}
---
# Hiring, configuration, and organization
Operators hire agents, configure their identity and instructions, assign reporting relationships, and manage their lifecycle. Built-in agents have their own setup and lifecycle constraints.
@@ -10,8 +14,10 @@ Agent access: [companion](../agent-access-map/agents.md).
- `hire`: choose identity, harness, model, and required account settings; edit
reporting relationships through the agent configuration afterward.
- `grok-bot`: experimental existing-Bot agent setup through remote OAuth, routine credentials, and an authenticated two-way challenge; current contact, stop and explicit recovery.
- `instructions`: edit agent configuration and instruction files with durable revisions.
- `organization`: inspect and change reporting relationships through supported controls.
- `primary-agent`: choose a personal primary agent for the company, confirm replacement, and inspect its roster/sidebar and task/chat defaults.
- `lifecycle`: pause/resume or retire an agent while preserving history.
- `built-in`: configure required agents without treating them as ordinary removable hires.
@@ -29,6 +35,11 @@ Open `/agents/:agentId` and the configuration/instruction surfaces it exposes.
Use the roster’s organization view; `/org` redirects to the roster in the streamlined shell.
### `personal-primary-agent`
Open an agent profile and choose **Set as my primary**. Inspect its crown on the
profile/roster and its position in the Agents sidebar, then open a new task or Chat.
## Driving it with Playwright and the Paperclip CLI
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use a disposable company and supported adapter; hiring may require a formal approval.
@@ -92,8 +103,34 @@ Automated: [org chart](../../ui/src/pages/OrgChart.test.tsx) is component eviden
Manual: Inspect a manager and report, change the relationship through the offered controls, and reload both views. Exercise a rejected invalid relationship. Configure a built-in agent and verify it retains its required identity and restrictions.
### `personal-primary-agent`
Automated: [primary-agent context](../../ui/src/context/PrimaryAgentProvider.test.tsx)
and [primary-agent routes](../../server/src/__tests__/primary-agent.test.ts)
cover selection, company/user scope, and request contracts.
Manual: Select an available agent, reload, and inspect the retained personal choice.
Replace it and verify confirmation is required. Leave or terminate the selected
agent through permitted controls and inspect the unavailable/cleared state.
Switch company/user to check isolation. Open a task and Chat with a
valid draft or recent selection; verify those explicit choices take precedence
over the primary fallback. Opening Chat must not start execution.
## Gotchas
- A roster entry is not proof of an authenticated or invokable adapter.
- Pending hires may live in approval/task surfaces rather than the active roster.
- Skill and tool grants are separate: see [skills](./skills.md) and [app permissions](./app-permissions.md).
- A personal primary agent is a per-user/company preference. It does not change
reporting lines, stars, permissions, or another person's primary agent.
### `connect-grok-bot`
Choose **Invite an external agent → Grok Bot**, identify the Bot by its desktop name, connect its remote MCP plugin, configure a webhook-only routine, and verify delivery plus authenticated reply. Save & exit resumes the same agent. Keep pairing codes in browser authorization and routine credentials in Paperclip’s fields. A working Bot web URL is not required.
Prerequisites: authenticated public HTTPS, Assistant connections (MCP), Paperclip Runner and Grok Bot experimental settings. Cloud uses its normal managed Runner environment. Provider usage is unknown. Routine uncertainty blocks new assignments until explicit inspection and recovery; stopping work revokes Paperclip authority without confirming remote termination.
Evidence: source implementation and focused protocol tests; real provider assigned/proactive workflows and deployed managed acceptance remain release gates.
### Documentation scope: Agents, organization, and runtime setup
Per-harness/model/account capabilities, every instruction-file error, and complete built-in-agent lifecycle variants remain separate qualification matrices.
maps/feature-map/app-permissions.md
+14 -1
View File
@@ -1,4 +1,8 @@
# App access, action permissions, and testing
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":20}
---
# App access and action permissions
After connecting an app, an operator decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access.
@@ -45,3 +49,12 @@ Manual: Run a read-only action with explicit inputs and inspect returned data an
- Connected does not imply an agent has access or an action is allowed.
- Credential-only connections may replace tool-action controls with account-specific controls.
- See [connection setup](./connection-setup.md) for auth and [questions and approvals](./questions-and-approvals.md) for pending action review.
### Storybook verification
#### `catalog-change`
Scope: ui
Storybook: Mount PermissionsPanel/AppDetail with quarantined actions, selection/review, refresh pending, empty and failed discovery states. Existing auto-allowed NewToolsAllowed examples are not quarantine review.
Production: Exercise catalog refresh and new-tool review with permitted/denied actors; unreviewed actions stay quarantined, prior Off/Ask choices survive refresh, and approved review persists.
Sources: Source: [PermissionsPanel.tsx](../../ui/src/pages/apps/app-detail/PermissionsPanel.tsx), [AppDetail.tsx](../../ui/src/pages/apps/AppDetail.tsx), [tool-access.ts](../../server/src/routes/tool-access.ts). Tests: [AppDetail.test.tsx](../../ui/src/pages/apps/AppDetail.test.tsx), [tool-access-service.test.ts](../../server/src/__tests__/tool-access-service.test.ts), [tool-access-policy-service.test.ts](../../server/src/__tests__/tool-access-policy-service.test.ts)
maps/feature-map/budgets-costs.md
+14 -1
View File
@@ -1,4 +1,8 @@
# Costs, budgets, and spending controls
---
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":10}
---
# Costs and budgets
Operators inspect recorded spend and configure budget controls for the company, projects, and agents. Hard stops pause or prevent eligible work until the governing incident is resolved.
@@ -47,3 +51,12 @@ Manual: Create a small fixture budget, cross its threshold with synthetic record
- Paperclip cost accounting is not a provider invoice or a promise about externally billed spend.
- Company, project, and agent gates can overlap; fixing one may leave another active.
- A successful retry must not bypass an unresolved budget hold.
### Storybook verification
#### `resolution`
Scope: ui
Storybook: Mount BudgetIncidentCard with entered raised limit, invalid limit, keep-paused, applying, authorized/blocked and error states wired through actual host. Existing matrix handlers are no-ops.
Production: POST /companies/{id}/budget-incidents/{id}/resolve must authorize scope-specific raise, persist resolution and resume eligible work while retaining overlapping budget/manual holds.
Sources: Source: [BudgetIncidentCard.tsx](../../ui/src/components/BudgetIncidentCard.tsx), [Costs.tsx](../../ui/src/pages/Costs.tsx), [budgets.ts](../../ui/src/api/budgets.ts), [costs.ts](../../server/src/routes/costs.ts), [budgets.ts](../../server/src/services/budgets.ts). Tests: [budgets-service.test.ts](../../server/src/__tests__/budgets-service.test.ts), [Costs.test.tsx](../../ui/src/pages/Costs.test.tsx)
maps/feature-map/cases.md
+35 -1
View File
@@ -1,4 +1,8 @@
# Cases and structured work records
---
navigation: {"section":"Automation and structured work","sectionOrder":60,"order":30}
---
# Cases
The cases experiment exposes structured records with types, fields, parent/child relationships, activity, revisions, and related task work.
@@ -49,3 +53,33 @@ pipeline-owned item from a stand-alone case.
- Feature gating and offered controls determine available actions. The API
accepts a string case type and arbitrary JSON fields; do not infer typed
case-field validation or a field-editing UI from those values.
### Storybook verification
#### `browse`
Scope: ui
Storybook: Mount Cases search/filter/sort/group/tree, matched-child parent context, persisted view choices, keyboard navigation and empty/loading/error.
Production: GET /companies/{id}/cases scope/filter behavior is production evidence; rendered fixtures establish presentation only. Mutation/permission scenarios need real API checks separately.
Sources: Source: [Cases.tsx](../../ui/src/pages/Cases.tsx), [cases.ts](../../server/src/routes/cases.ts). Tests: [Cases.test.tsx](../../ui/src/pages/Cases.test.tsx), [cases-routes.test.ts](../../server/src/__tests__/cases-routes.test.ts)
#### `structure`
Scope: ui
Storybook: Mount CaseDetail and CaseFieldsPanel with arbitrary JSON fields and parent/children, matching descendants and unavailable child. Do not invent a general field editor or typed field validation.
Production: GET /cases/{id} and /cases/{id}/children/tree must return permitted company records and correct relationships; changes/persistence require route tests separately.
Sources: Source: [CaseDetail.tsx](../../ui/src/pages/CaseDetail.tsx), [CaseFieldsPanel.tsx](../../ui/src/components/CaseFieldsPanel.tsx), [Cases.tsx](../../ui/src/pages/Cases.tsx), [cases.ts](../../server/src/routes/cases.ts), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [CaseFieldsPanel.test.tsx](../../ui/src/components/CaseFieldsPanel.test.tsx), [Cases.test.tsx](../../ui/src/pages/Cases.test.tsx), [CaseDetail.test.tsx](../../ui/src/pages/CaseDetail.test.tsx), [cases-routes.test.ts](../../server/src/__tests__/cases-routes.test.ts)
#### `history`
Scope: ui
Storybook: Mount CaseDetail activity and document revisions as distinct views, empty/loading/errors, attribution and source links.
Production: GET /cases/{id}/events and /cases/{id}/documents/{key}/revisions require company/access filtering; a fixture list does not establish durable revision creation or restoration.
Sources: Source: [CaseDetail.tsx](../../ui/src/pages/CaseDetail.tsx), [cases.ts](../../server/src/routes/cases.ts). Tests: [CaseDetail.test.tsx](../../ui/src/pages/CaseDetail.test.tsx), [cases-routes.test.ts](../../server/src/__tests__/cases-routes.test.ts)
#### `task-links`
Scope: ui
Storybook: Mount CaseDetail and IssueCasesPanel related-task/case links in both directions, missing links and unavailable targets.
Production: GET /issues/{id}/cases and /cases/{id}/issue-links must enforce permitted task/case relationships; production browser cold links verify destination and company context.
Sources: Source: [CaseDetail.tsx](../../ui/src/pages/CaseDetail.tsx), [IssueCasesPanel.tsx](../../ui/src/components/IssueCasesPanel.tsx), [cases.ts](../../server/src/routes/cases.ts), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [IssueCasesPanel.test.tsx](../../ui/src/components/IssueCasesPanel.test.tsx), [CaseDetail.test.tsx](../../ui/src/pages/CaseDetail.test.tsx), [cases-routes.test.ts](../../server/src/__tests__/cases-routes.test.ts)
maps/feature-map/chat-channels.md
+46 -2
View File
@@ -1,4 +1,8 @@
# External chat and email conversations
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":30}
---
# External chat and email
People can talk to an assigned agent through configured external channels, bind their identity, exchange files, and inspect delivery state. Each provider has a different identity, threading, and attachment contract.
@@ -8,7 +12,7 @@ Agent access: [companion](../agent-access-map/chat-channels.md).
## Sub-features
- `providers`: configure the available Slack, Discord, Microsoft Teams, Telegram, GitHub, AgentMail, and experimental iMessage Photon paths; availability still depends on gates and provider support.
- `providers`: configure the available Slack, Discord, Microsoft Teams, Telegram, GitHub, AgentMail, and experimental iMessage Photon and Speko paths; availability still depends on gates and provider support.
- `identity`: link the external sender to the intended authorized Paperclip identity.
- `conversation`: route inbound messages to the selected agent and send replies to the correct thread.
- `attachments`: transfer supported files with inspectable delivery and failure states.
@@ -38,17 +42,44 @@ Automated: [channel integration](../../server/src/__tests__/chat-channels.integr
Manual: For each supported provider being changed, send a unique message, verify the intended agent/company receives it, and inspect the actual external reply in the original thread. Repeat with an unlinked/unauthorized sender, duplicate inbound delivery, and one supported attachment. Record provider-specific results separately.
For Slack, enable **Require at-mention** and **Allow direct messages**. Send a
plain DM and follow up without a mention: both should reach the agent, with
top-level replies to top-level DMs. Channel messages and thread replies still
require a mention when that setting is enabled. Disable direct messages and
confirm a plain DM is rejected. Use a private channel for threaded conversations.
### `endpoint-management`
Automated: [channel integration](../../server/src/__tests__/chat-channels.integration.test.ts) covers shared endpoint/delivery behavior; live credential repair and provider ownership remain manual checks.
Manual: Inspect the bound agent and identity, recent activity, and delivery failure details. Repair a disposable credential, retry a safe message when offered, and verify exactly one external reply. Disable the endpoint and confirm new traffic is not silently processed.
For GitHub, submit a disposable PR and verify the summary heading uses the bot's
display name and the check remains **Paperclip Review**. For two separate bots on one PR, verify
their App-scoped checks and comments remain independent.
For GitHub publication recovery, interrupt a response after GitHub accepts a
write and verify one summary, finding, and App-scoped check. Retry the same tool
call and verify it returns the saved receipt. Leave a transient failure queued,
restart the instance, and verify publication resumes at its saved deadline
without another inbound message. Revoked access and permanent rejections must
stop retries. These recipes are separate from live provider proof.
Configure optional project and workspace defaults at the connection and destination
levels. Start a new conversation and inspect its task workspace. Verify that
inheritance, an explicit selection, and clearing a default remain distinct.
Changing defaults must not move an existing conversation or interrupt its run.
For experimental Speko, enable chat connectors, choose an agent during setup,
and verify the provider credentials. On an assigned task, use **Talk to agent**
to open browser voice controls. Check microphone denial, mute, end/restart,
navigation during a call, and access revocation. Inspect transcripts and the
connection's call history. Callback preferences, incoming phone configuration,
and incoming-call approval are separate settings and authorization journeys.
The [voice components](../../ui/src/components/voice/TaskVoiceLauncher.tsx)
and fixture tests cover presentation; they do not establish live answer retrieval
or telephone playback. Those provider outcomes remain explicit release gates.
## Gotchas
- Visibility flags do not pause existing delivery. Disable the disposable
@@ -57,3 +88,16 @@ Changing defaults must not move an existing conversation or interrupt its run.
- One provider’s passing fixture does not qualify another provider or live delivery.
- An accepted send request does not prove the recipient received the message or file.
- Use [steering](./steering.md) and [questions](./questions-and-approvals.md) for their channel-specific interaction checks.
### Storybook verification
#### `attachments`
Scope: ui
Storybook: Mount TaskChatBubble attachments and ChatEndpointDetail provider-specific consent/upload/delivery failure and unknown-outcome states. Local email attachment dialog remains a prototype.
Production: Transfer a disposable supported file through each affected provider; verify recipient delivery, read scope, duplicate/replay handling and failure/unknown state without treating notification as file-upload proof.
Sources: Source: [TaskChatBubble.tsx](../../ui/src/components/task-chat/TaskChatBubble.tsx), [ChatEndpointDetail.tsx](../../ui/src/pages/apps/chat/ChatEndpointDetail.tsx), [chatEndpoints.ts](../../ui/src/api/chatEndpoints.ts), [chat-channels.ts](../../server/src/routes/chat-channels.ts). Tests: [TaskChatBubble.test.tsx](../../ui/src/components/task-chat/TaskChatBubble.test.tsx), [task-chat-attachments.test.ts](../../ui/src/components/task-chat/task-chat-attachments.test.ts), [chat-channels.integration.test.ts](../../server/src/__tests__/chat-channels.integration.test.ts), [issue-attachment-routes.test.ts](../../server/src/__tests__/issue-attachment-routes.test.ts)
### Documentation scope: Chat and email channel setup
Shared recipes name provider checks; each provider transport/thread/identity/file-size/type combination needs separate live evidence and deeper instructions.
maps/feature-map/cli-operations.md
+42 -1
View File
@@ -1,4 +1,8 @@
# CLI, API clients, and local worktrees
---
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":50}
---
# CLI/API and local worktrees
Operators and agents can work through explicit CLI/API context, manage domain resources, inspect runs, and create isolated local worktree instances for development.
@@ -60,3 +64,40 @@ Manual: Initialize an owned disposable worktree instance, inspect its printed pa
- API success proves its contract, not the equivalent browser creation journey.
- The CLI command registry is broader than the UI page inventory; new command families need a recipe review.
- See [instance operations](./instance-operations.md) for install/update/backup and feature-specific recipes for domain behavior.
### Storybook verification
#### `context`
Scope: cli
Storybook: No authored story required for CLI profile/context selection.
Production: Verify selected API origin, identity and company, JSON output and invalid-token/wrong-company failures. A persona label is not authentication.
Sources: Source: [context.ts](../../cli/src/commands/client/context.ts). Tests: [context.test.ts](../../cli/src/__tests__/context.test.ts), [http.test.ts](../../cli/src/__tests__/http.test.ts)
#### `domain-commands`
Scope: cli
Storybook: No authored story required for command parsing and domain API execution; corresponding product UI keeps its own story needs.
Production: Discover registered help, use a disposable company, assert persisted mutations and denied operations with the actual actor. Command parity is not every endpoint passing live.
Sources: Source: [index.ts](../../cli/src/index.ts), [issue.ts](../../cli/src/commands/client/issue.ts). Tests: [operations-parity.test.ts](../../cli/src/__tests__/operations-parity.test.ts)
#### `outputs`
Scope: cli
Storybook: No authored story required for CLI document/asset/skill IO or machine-readable output.
Production: Assert payload/schema, exit code, written contents, authorization and file integrity. Open the resulting document/asset in the product for cross-surface acceptance.
Sources: Source: [issue.ts](../../cli/src/commands/client/issue.ts), [asset.ts](../../cli/src/commands/client/asset.ts), [skill.ts](../../cli/src/commands/client/skill.ts). Tests: [issue-subresources.test.ts](../../cli/src/__tests__/issue-subresources.test.ts), [admin-asset-skill-parity.test.ts](../../cli/src/__tests__/admin-asset-skill-parity.test.ts)
#### `run-controls`
Scope: cli
Storybook: No authored story required for invoke/list/get/cancel/events/log command execution.
Production: Assert the real run ID, event/log output and resulting state, eligible actor and cancellation denial. Printed success does not prove provider completion.
Sources: Source: [run.ts](../../cli/src/commands/client/run.ts), [heartbeat-run.ts](../../cli/src/commands/heartbeat-run.ts). Tests: [operations-parity.test.ts](../../cli/src/__tests__/operations-parity.test.ts)
#### `worktree-instances`
Scope: cli
Storybook: No authored story required for worktree initialize/seed/repair/cleanup commands.
Production: Use only an owned isolated checkout/instance; verify paths, ports, health, login and seed provenance, then cleanup ownership. Capture evidence before teardown.
Sources: Source: [worktree.ts](../../cli/src/commands/worktree.ts), [test-drive.ts](../../cli/src/commands/test-drive.ts). Tests: [worktree.test.ts](../../cli/src/__tests__/worktree.test.ts), [test-drive.test.ts](../../cli/src/__tests__/test-drive.test.ts)
maps/feature-map/companies.md
+59
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Getting started and access","sectionOrder":10,"order":30}
---
# Companies and portability
An operator can switch between companies, change their identity and settings, archive them, and preview an import or export. Each company remains a separate scope for work and agents.
@@ -10,6 +14,8 @@ Agent access: [companion](../agent-access-map/companies.md).
- `selection`: create/select a company and keep navigation in its scope.
- `identity`: update company identity and configured settings.
- `decision-models`: configure and test the company's decision model, then inspect invocation history and recorded usage.
- `fast-responses`: configure and test the experimental fast-response service, then inspect acknowledgement history, failures, and recorded usage.
- `archive`: archive and restore through the available controls without confusing archival with deletion.
- `portability`: preview a company package and inspect imported agents, projects, skills, and conflicts.
@@ -23,6 +29,12 @@ Use the company switcher or `/companies`, then enter company Settings.
Use `/company/export` and `/company/import` where enabled, or the corresponding CLI company commands.
### `company-ai-services`
Use Settings → Connections (`/company/settings/connections`) when fast responses
are enabled. Otherwise decision-model settings remain in Company Settings.
Open the Decisions and Fast responses tabs in Costs to inspect invocation history.
## Driving it with Playwright and the Paperclip CLI
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use two disposable companies and a small package fixture. Record cloud-managed restrictions and visible settings gates.
@@ -39,6 +51,22 @@ Automated: [portability routes](../../server/src/__tests__/company-portability-r
Manual: Export a small company, inspect the package preview, and import into a disposable target. Verify counts, references, conflict choices, and agent configuration. Run one imported task after supplying its required local credentials. Confirm source company data is unchanged.
### `company-ai-services`
Automated: [decision settings](../../ui/src/components/decision-models/DecisionModelSettings.test.tsx),
[decision history](../../ui/src/components/decision-models/DecisionHistory.test.tsx),
[fast-response settings](../../ui/src/components/fast-responses/FastResponseSettings.test.tsx),
[decision service](../../server/src/__tests__/decision-models.test.ts), and
[fast-response service](../../server/src/__tests__/fast-responses.test.ts) cover
component and service contracts with simulated providers.
Manual: As an authorized connection manager, select a disposable shared AI
connection, save the provider/model and sponsorship options, reload, and run the
bounded Test action. Inspect success and failure receipts and their history in
Costs. Verify disabled or revoked connections remain clear and that a user
without connection-management permission cannot configure or test the service.
Use an owned provider fixture for failure states; record any actual provider usage.
## Gotchas
- Restore an archived company through `/companies` → its menu → **Unarchive**.
@@ -48,3 +76,34 @@ Manual: Export a small company, inspect the package preview, and import into a d
- Package presence does not prove a runnable imported company; credentials and environment bindings need separate verification.
- Company deletion is a distinct gated operation; do not use it as the archive test.
- Settings hidden in a managed deployment should be recorded as unavailable, not bypassed.
- Decision tests and fast responses have different request and execution contracts.
A fast-response receipt is an acknowledgement, not completed agent work.
History visibility and connection-management authority are separate; task links
in history also require access to the underlying task.
### Storybook verification
#### `selection`
Scope: ui
Storybook: Company list/create/switcher; empty, loading, error, unavailable company and switched navigation.
Production: Switch and reload between companies; verify tasks/agents/cache/routes remain scoped and unauthorized company requests fail.
Sources: Source: [Companies.tsx](../../ui/src/pages/Companies.tsx), [CompanySwitcher.tsx](../../ui/src/components/CompanySwitcher.tsx), [CompanyContext.tsx](../../ui/src/context/CompanyContext.tsx). Tests: [Companies.test.tsx](../../ui/src/pages/Companies.test.tsx), [CompanyContext.test.tsx](../../ui/src/context/CompanyContext.test.tsx), [companies-route-cross-company-authz.test.ts](../../server/src/__tests__/companies-route-cross-company-authz.test.ts)
#### `archive`
Scope: ui
Storybook: Archive confirmation, pending/error and departure navigation; archived list entry and Unarchive action.
Production: Archive eligible agents/runs without deleting history; restoration handles archival-specific pause and navigates to correct company.
Sources: Source: [CompanySettings.tsx](../../ui/src/pages/CompanySettings.tsx), [Companies.tsx](../../ui/src/pages/Companies.tsx), [companies.ts](../../ui/src/api/companies.ts). Tests: [CompanySettingsArchive.test.tsx](../../ui/src/pages/CompanySettingsArchive.test.tsx), [Companies.test.tsx](../../ui/src/pages/Companies.test.tsx), [companies-service.test.ts](../../server/src/__tests__/companies-service.test.ts)
#### `portability`
Scope: ui
Storybook: Import/export preview, conflict choice, warnings, async progress/failure/success and restricted managed deployment.
Production: Apply real small package to disposable target; inspect counts/references/conflicts, source immutability and credential exclusions; imported task requires separate runnable-account proof.
Sources: Source: [CompanyImport.tsx](../../ui/src/pages/CompanyImport.tsx), [CompanyExport.tsx](../../ui/src/pages/CompanyExport.tsx), [companies.ts](../../ui/src/api/companies.ts). Tests: [CompanyImport.test.tsx](../../ui/src/pages/CompanyImport.test.tsx), [CompanyExport.test.tsx](../../ui/src/pages/CompanyExport.test.tsx), [company-portability-routes.test.ts](../../server/src/__tests__/company-portability-routes.test.ts), [company-import-export-e2e.test.ts](../../cli/src/__tests__/company-import-export-e2e.test.ts)
### Documentation scope: Company and instance administration
Core administration/import/export/operator workflows are mapped; cloud/self-hosted differences, migration/restore compatibility, and platform-specific service variants need deeper recipes.
maps/feature-map/connection-setup.md
+16
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":10}
---
# Connection setup
People connect an app or account, choose who may use it, and recover incomplete
@@ -104,6 +108,8 @@ Test no-auth and authenticated endpoints separately; never infer one from the ot
Automated: [interaction card](../../ui/src/components/IssueThreadInteractionCard.test.tsx)
checks addressed-user controls. AppsConnect tests cover page/dialog parity,
task-bound OAuth, popup handoff, and verifying a saved connection before closing.
Withdrawn requests render a terminal acknowledgement with no setup action; the
interaction-body test and narrow Storybook journey cover this recovery state.
The connection-intents browser suite above exercises fixture-backed continuation.
Manual: ask an agent to use an unavailable app, open its request as the named
@@ -132,6 +138,12 @@ Automated: [setup routing](../../ui/src/pages/apps/chat/ChatEndpointSetup.routin
[identity confirmation](../../ui/src/pages/apps/chat/ChatIdentityConfirm.test.tsx)
cover shared UI logic with fixtures. Provider-specific live setup is not implied.
[Channel integration](../../server/src/__tests__/chat-channels.integration.test.ts)
also covers bounded Telegram subscription recovery at startup and after committed
configuration changes, saved retry deadlines, rollback, and parking pending
repair while an endpoint or connection is inactive. The provider responses are
fixtures. Settled maintenance leaves no discovery timer or database scans.
Manual: complete setup for one named provider, reload endpoint settings, link
the intended sender, and send a disposable message. Verify one task and a useful
reply in the originating conversation. Inspect an unlinked sender's denial and
@@ -154,3 +166,7 @@ Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage.
- Full provider matrix, AI-account selection, gateway/profile administration,
and account revocation lifecycles remain outside this seed recipe.
- For governed actions after setup, use [questions and approvals](./questions-and-approvals.md).
### Documentation scope: App catalog and connection setup
Provider-specific authentication/revocation, credential-only accounts, and aggregator administrative variants still need their own detailed matrices.
maps/feature-map/coverage.json
-401
View File
@@ -1,401 +0,0 @@
{
"version": 1,
"areas": [
{
"id": "tasks-and-attention",
"title": "Tasks, conversations, and attention",
"status": "partial",
"features": [
"tasks.md",
"task-coordination.md",
"inbox-search.md",
"agent-chat.md",
"questions-and-approvals.md",
"steering.md",
"recovery.md",
"documents-artifacts.md"
],
"gap": "Recipes cover the main task/conversation/attention workflows. Full shell, permission, attachment, long-thread, and concurrency permutations remain to be enumerated.",
"paths": [
"ui/src/pages/AgentChat.tsx",
"ui/src/pages/AgentChats.tsx",
"ui/src/pages/BoardChat.tsx",
"ui/src/pages/DecisionQueuePage.tsx",
"ui/src/pages/Inbox.tsx",
"ui/src/pages/IssueDetail.tsx",
"ui/src/pages/Issues.tsx",
"ui/src/pages/LegacyInbox.tsx",
"ui/src/pages/MyIssues.tsx",
"ui/src/pages/Search.tsx",
"ui/src/pages/WhatNeedsMe.tsx"
]
},
{
"id": "agents",
"title": "Agents, organization, and runtime setup",
"status": "partial",
"features": [
"agents.md",
"runs-adapters.md",
"skills.md",
"app-permissions.md",
"recovery.md",
"execution-environments.md"
],
"gap": "Per-harness/model/account capabilities, every instruction-file error, and complete built-in-agent lifecycle variants remain separate qualification matrices.",
"paths": [
"ui/src/pages/AdapterManager.tsx",
"ui/src/pages/AgentDetail.production.tsx",
"ui/src/pages/AgentDetail.tsx",
"ui/src/pages/AgentToolsTab.tsx",
"ui/src/pages/Agents.production.tsx",
"ui/src/pages/Agents.tsx",
"ui/src/pages/NewAgent.tsx",
"ui/src/pages/Org.tsx",
"ui/src/pages/OrgChart.production.tsx",
"ui/src/pages/OrgChart.tsx"
]
},
{
"id": "apps",
"title": "App catalog and connection setup",
"status": "partial",
"features": [
"connection-setup.md",
"app-permissions.md",
"questions-and-approvals.md"
],
"gap": "Provider-specific authentication/revocation, credential-only accounts, and aggregator administrative variants still need their own detailed matrices.",
"paths": [
"ui/src/pages/apps/AggregatorAppManager.tsx",
"ui/src/pages/apps/AggregatorConnectDialog.tsx",
"ui/src/pages/apps/AppDetail.tsx",
"ui/src/pages/apps/AppLogo.tsx",
"ui/src/pages/apps/AppNotConnected.tsx",
"ui/src/pages/apps/AppsConnect.tsx",
"ui/src/pages/apps/AppsReview.tsx",
"ui/src/pages/apps/ArcadeDiscoverySetup.tsx",
"ui/src/pages/apps/Browse.tsx",
"ui/src/pages/apps/CatalogSourceFilters.tsx",
"ui/src/pages/apps/ComposioAppManager.tsx",
"ui/src/pages/apps/ComposioAppSetup.tsx",
"ui/src/pages/apps/ConnectionProvenanceChip.tsx",
"ui/src/pages/apps/Connections.tsx",
"ui/src/pages/apps/ExecutorManagementSetup.tsx",
"ui/src/pages/apps/PaperclipCloudOAuthHandoff.tsx",
"ui/src/pages/apps/ReviewQueueCard.tsx",
"ui/src/pages/apps/UnverifiedServerBadge.tsx",
"ui/src/pages/apps/app-detail/ActionTestDialog.tsx",
"ui/src/pages/apps/app-detail/ActivityPanel.tsx",
"ui/src/pages/apps/app-detail/AdvancedPanel.tsx",
"ui/src/pages/apps/app-detail/AgentConnectionAccess.tsx",
"ui/src/pages/apps/app-detail/BrowserUseSettingsPanel.tsx",
"ui/src/pages/apps/app-detail/ConnectedAggregatorApps.tsx",
"ui/src/pages/apps/app-detail/IdentitiesSection.tsx",
"ui/src/pages/apps/app-detail/PermissionsPanel.tsx",
"ui/src/pages/apps/app-detail/RailwayAccessPanel.tsx",
"ui/src/pages/apps/app-detail/ReviewPanel.tsx",
"ui/src/pages/apps/app-detail/SetupPanel.tsx",
"ui/src/pages/apps/connection-owner.tsx"
]
},
{
"id": "chat-channels",
"title": "Chat and email channel setup",
"status": "partial",
"features": [
"chat-channels.md",
"connection-setup.md",
"questions-and-approvals.md",
"steering.md"
],
"gap": "Shared recipes name provider checks; each provider transport/thread/identity/file-size/type combination needs separate live evidence and deeper instructions.",
"paths": [
"ui/src/pages/apps/chat/ChatCommunicationInstructions.tsx",
"ui/src/pages/apps/chat/ChatEndpointDetail.tsx",
"ui/src/pages/apps/chat/ChatEndpointSetup.tsx",
"ui/src/pages/apps/chat/ChatIdentityConfirm.tsx",
"ui/src/pages/apps/chat/EmailEndpointSetup.tsx",
"ui/src/pages/apps/chat/GitHubBotConfiguration.tsx",
"ui/src/pages/apps/chat/GitHubBotManagement.tsx",
"ui/src/pages/apps/chat/GitHubChatSetup.tsx",
"ui/src/pages/apps/chat/GitHubSetupPrompt.tsx",
"ui/src/pages/apps/chat/PhotonConnectStep.tsx",
"ui/src/pages/apps/chat/SetupPrompt.tsx",
"ui/src/pages/apps/chat/SlackAvatarStep.tsx",
"ui/src/pages/apps/chat/SlackIdentityStep.tsx",
"ui/src/pages/apps/chat/SlackSetupPrompt.tsx",
"ui/src/pages/apps/chat/SlackToolSettings.tsx"
]
},
{
"id": "skills-and-teams",
"title": "Skills, Skill Studio, and teams",
"status": "partial",
"features": [
"skills.md",
"teams.md",
"questions-and-approvals.md"
],
"gap": "Main library/Studio/source/policy and CLI team-install paths are mapped. Full source-provider conflicts, harness sync, and remote package variants remain; catalog UI is not a current top-level route.",
"paths": [
"ui/src/pages/CompanySkills.production.tsx",
"ui/src/pages/CompanySkills.tsx",
"ui/src/pages/SkillSources.tsx",
"ui/src/pages/SkillStudio.tsx",
"ui/src/pages/TeamCatalog.tsx",
"ui/src/pages/agent-skills/AgentSkillReleasePicker.tsx",
"ui/src/pages/agent-skills/AgentSkillRow.tsx",
"ui/src/pages/agent-skills/AgentSkillsTab.tsx",
"ui/src/pages/skills/ImportSkillsFromProjectDialog.tsx",
"ui/src/pages/skills/SkillImportProgress.tsx",
"ui/src/pages/skills/SkillPackagePreview.tsx",
"ui/src/pages/skills/SkillSourceTree.tsx"
]
},
{
"id": "projects-and-workspaces",
"title": "Projects and execution workspaces",
"status": "partial",
"features": [
"projects.md",
"workspaces.md",
"goals.md",
"execution-environments.md",
"budgets-costs.md",
"recovery.md"
],
"gap": "Provider-specific provisioning, multi-repository/submodule edge cases, Git reconciliation variants, and all service exposure combinations require deeper recipes.",
"paths": [
"ui/src/pages/ExecutionWorkspaceDetail.tsx",
"ui/src/pages/ProjectDetail.tsx",
"ui/src/pages/ProjectWorkspaceDetail.tsx",
"ui/src/pages/Projects.tsx",
"ui/src/pages/Workspaces.tsx"
]
},
{
"id": "formal-approvals",
"title": "Formal governance approvals",
"status": "partial",
"features": [
"questions-and-approvals.md",
"task-coordination.md",
"agents.md"
],
"gap": "Formal board decisions and signoff have recipes; every approval payload/type and actor/host error permutation is not enumerated.",
"paths": [
"ui/src/pages/ApprovalDetail.tsx",
"ui/src/pages/Approvals.tsx"
]
},
{
"id": "auth-and-access",
"title": "Login, invitations, and access",
"status": "partial",
"features": [
"onboarding.md",
"access.md",
"navigation-preferences.md",
"cli-operations.md"
],
"gap": "Deployment modes and core login/invite/member/token paths are mapped; exhaustive identity-provider, expiry, role, and resource-policy combinations remain.",
"paths": [
"ui/src/pages/Auth.tsx",
"ui/src/pages/BoardClaim.tsx",
"ui/src/pages/CliAuth.tsx",
"ui/src/pages/CompanyAccess.tsx",
"ui/src/pages/InstanceAccess.tsx",
"ui/src/pages/InviteLanding.tsx",
"ui/src/pages/JoinRequestQueue.tsx",
"ui/src/pages/UserProfile.tsx"
]
},
{
"id": "company-and-instance",
"title": "Company and instance administration",
"status": "partial",
"features": [
"companies.md",
"onboarding.md",
"instance-operations.md",
"execution-environments.md",
"navigation-preferences.md"
],
"gap": "Core administration/import/export/operator workflows are mapped; cloud/self-hosted differences, migration/restore compatibility, and platform-specific service variants need deeper recipes.",
"paths": [
"ui/src/pages/Companies.tsx",
"ui/src/pages/CompanyEnvironments.tsx",
"ui/src/pages/CompanyExport.tsx",
"ui/src/pages/CompanyImport.tsx",
"ui/src/pages/CompanySettings.tsx",
"ui/src/pages/InstanceExperimentalSettings.tsx",
"ui/src/pages/InstanceGeneralSettings.tsx",
"ui/src/pages/ProfileSettings.tsx"
]
},
{
"id": "goals-costs-and-activity",
"title": "Goals, dashboards, costs, and activity",
"status": "partial",
"features": [
"goals.md",
"budgets-costs.md",
"activity.md",
"runs-adapters.md",
"routines.md"
],
"gap": "Core goal/report/budget/audit journeys are mapped. Every aggregation/filter combination, cost source, and overlapping budget window still needs dedicated cases.",
"paths": [
"ui/src/pages/Costs.production.tsx",
"ui/src/pages/Costs.tsx",
"ui/src/pages/Dashboard.tsx",
"ui/src/pages/DashboardLive.tsx",
"ui/src/pages/GoalDetail.tsx",
"ui/src/pages/Goals.tsx",
"ui/src/pages/Timeline.tsx",
"ui/src/pages/audit/AuditFeed.production.tsx",
"ui/src/pages/audit/AuditFeed.tsx",
"ui/src/pages/audit/AuditHub.tsx",
"ui/src/pages/audit/AuditRuns.tsx",
"ui/src/pages/audit/CompanyActivity.production.tsx",
"ui/src/pages/audit/CompanyActivity.tsx",
"ui/src/pages/audit/RoutineAuditActivity.tsx"
]
},
{
"id": "artifacts",
"title": "Artifacts and work products",
"status": "partial",
"features": [
"documents-artifacts.md"
],
"gap": "Document/attachment/library/work-product journeys are mapped; every media preview type, storage backend, annotation conflict, and runtime-resource lifecycle variant remains separate.",
"paths": [
"ui/src/pages/Artifacts.tsx"
]
},
{
"id": "routines-and-pipelines",
"title": "Routines, pipelines, cases, and status cards",
"status": "partial",
"features": [
"routines.md",
"pipelines.md",
"cases.md",
"status-cards.md"
],
"gap": "All four capabilities have recipes. Trigger/provider/timezone combinations, custom case schemas, stage automation types, and summarizer quality need deeper cases.",
"paths": [
"ui/src/pages/CaseDetail.tsx",
"ui/src/pages/Cases.tsx",
"ui/src/pages/PipelineSettings.tsx",
"ui/src/pages/Pipelines.tsx",
"ui/src/pages/RoutineDetail.production.tsx",
"ui/src/pages/RoutineDetail.tsx",
"ui/src/pages/Routines.production.tsx",
"ui/src/pages/Routines.tsx",
"ui/src/pages/StatusCards/ArchivedStatusCardRow.tsx",
"ui/src/pages/StatusCards/CreateStatusCardDialog.tsx",
"ui/src/pages/StatusCards/StatusCardDetailDrawer.tsx",
"ui/src/pages/StatusCards/StatusCardSettingsForm.tsx",
"ui/src/pages/StatusCards/StatusCardTile.tsx",
"ui/src/pages/StatusCards/SummarizerAgentSelect.tsx",
"ui/src/pages/StatusCards/index.tsx"
]
},
{
"id": "secrets",
"title": "Secrets and secret proposals",
"status": "partial",
"features": [
"secrets.md",
"access.md",
"app-permissions.md"
],
"gap": "Company/user/proposal/vault and runtime-binding paths are mapped; every secret provider, rotation scenario, and delivery context needs separate validation.",
"paths": [
"ui/src/pages/Secrets.tsx",
"ui/src/pages/secrets/ImportFromVaultDialog.tsx",
"ui/src/pages/secrets/MissingUserSecretsBanner.tsx",
"ui/src/pages/secrets/MyUserSecretsTab.tsx",
"ui/src/pages/secrets/ProposalsTab.tsx",
"ui/src/pages/secrets/SecretPathName.tsx",
"ui/src/pages/secrets/SetMyUserSecretDialog.tsx",
"ui/src/pages/secrets/UserSecretDefinitionsTab.tsx",
"ui/src/pages/secrets/proposal-review.tsx",
"ui/src/pages/secrets/user-secret-presentation.tsx"
]
},
{
"id": "plugins-and-tools",
"title": "Plugins, gateways, and tool profiles",
"status": "partial",
"features": [
"plugins.md",
"gateways-profiles.md",
"app-permissions.md",
"execution-environments.md"
],
"gap": "Host plugin/gateway/profile lifecycles are mapped. Third-party plugin behaviors and every client transport/provider combination are outside host-wide coverage.",
"paths": [
"ui/src/pages/CompanySettingsPluginPage.tsx",
"ui/src/pages/PluginManager.tsx",
"ui/src/pages/PluginPage.tsx",
"ui/src/pages/PluginSettings.tsx",
"ui/src/pages/apps/gateways/ConnectClientDialog.tsx",
"ui/src/pages/apps/gateways/CopyableGatewayUrl.tsx",
"ui/src/pages/apps/gateways/EditGatewayDialog.tsx",
"ui/src/pages/apps/gateways/GatewayDetail.tsx",
"ui/src/pages/apps/gateways/GatewaysList.tsx",
"ui/src/pages/apps/gateways/NewGatewayDialog.tsx",
"ui/src/pages/apps/gateways/panels/AppsToolsPanel.tsx",
"ui/src/pages/apps/gateways/panels/GatewayActivityPanel.tsx",
"ui/src/pages/apps/gateways/panels/GatewayAdvancedPanel.tsx",
"ui/src/pages/apps/gateways/panels/OverviewPanel.tsx",
"ui/src/pages/apps/gateways/panels/TokensPanel.tsx",
"ui/src/pages/tools/AdvancedToolsRoute.tsx",
"ui/src/pages/tools/AuditTab.tsx",
"ui/src/pages/tools/GatewaysTab.tsx",
"ui/src/pages/tools/McpConfigHelpDialog.tsx",
"ui/src/pages/tools/PasteConfigTab.tsx",
"ui/src/pages/tools/ProfilesTab.tsx",
"ui/src/pages/tools/SmokeLabTab.tsx",
"ui/src/pages/tools/ToolsAccess.tsx",
"ui/src/pages/tools/connection-dialogs.tsx",
"ui/src/pages/tools/profiles/ProfileActionDialog.tsx",
"ui/src/pages/tools/profiles/ProfileDetail.tsx",
"ui/src/pages/tools/profiles/ProfileDetailRoute.tsx",
"ui/src/pages/tools/profiles/ProfileWizard.tsx",
"ui/src/pages/tools/profiles/ProfileWizardRoute.tsx",
"ui/src/pages/tools/profiles/ProfilesIndex.tsx",
"ui/src/pages/tools/profiles/ToolsAdminGate.tsx",
"ui/src/pages/tools/profiles/WizardToolsStep.tsx",
"ui/src/pages/tools/shared.tsx"
]
},
{
"id": "labs-and-fallbacks",
"title": "Developer labs and fallback pages",
"status": "partial",
"features": [
"developer-labs.md",
"navigation-preferences.md"
],
"gap": "Developer and fallback surfaces are identified. Each synthetic fixture and performance budget is not a production journey and needs its own measurement.",
"paths": [
"ui/src/pages/BootstrapSetupUxLab.tsx",
"ui/src/pages/CrossIssueCollaborationUxLab.tsx",
"ui/src/pages/DesignGuide.tsx",
"ui/src/pages/InviteUxLab.tsx",
"ui/src/pages/IssueChatLongThreadPerf.tsx",
"ui/src/pages/IssueChatUxLab.tsx",
"ui/src/pages/NotFound.tsx",
"ui/src/pages/ResponsibleUserDenialUxLab.tsx",
"ui/src/pages/RunTranscriptUxLab.tsx",
"ui/src/pages/SystemNoticeUxLab.tsx",
"ui/src/pages/TaskChatLab.tsx"
]
}
]
}
maps/feature-map/developer-labs.md
+24
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Contributor surfaces","sectionOrder":80,"order":10}
---
# Developer previews and diagnostic labs
Contributors can inspect design examples, interaction labs, and performance fixtures. These are development surfaces and do not count as production feature verification.
@@ -48,3 +52,23 @@ real-task behavior before extrapolating fixture measurements.
- Intended developer use is not a universal runtime gate: Design Guide and
global lab/performance routes are also registered in production builds.
- Screenshots of a lab do not prove live provider behavior, persistence, or authorization.
### Storybook verification
#### `performance`
Scope: browser
Storybook: A screenshot/story is optional context, not the required performance evidence.
Production: Use existing browser performance harnesses. Record build/browser/data size, timing/trace and scrolling. Long-thread fixture has a disabled composer; task-chat HTML harness uses a plain textarea and simulated updates.
Sources: Source: [IssueChatLongThreadPerf.tsx](../../ui/src/pages/IssueChatLongThreadPerf.tsx), [README.md](../../tests/perf/task-chat/README.md), [README.md](../../tests/perf/issue-detail/README.md). Tests: [scrollback.spec.ts](../../tests/perf/task-chat/scrollback.spec.ts), [issue-detail.perf.spec.ts](../../tests/perf/issue-detail/issue-detail.perf.spec.ts)
#### `route-gates`
Scope: browser
Storybook: No isolated story required to prove actual route registration, redirects or gates; isolated gated-control examples remain useful.
Production: Drive real routes under their actual development, experimental, production and fallback settings. Do not assume every lab is dev-only: global long-thread/lab/design routes also exist in production registration.
Sources: Source: [App.tsx](../../ui/src/App.tsx). Tests: No dedicated test asserted; use the feature recipe.
### Documentation scope: Developer labs and fallback pages
Developer and fallback surfaces are identified. Each synthetic fixture and performance budget is not a production journey and needs its own measurement.
maps/feature-map/documents-artifacts.md
+17
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":70}
---
# Documents, attachments, and work products
People read and revise task documents, annotate specific content, open attached files, and inspect the outputs an agent hands back. The artifact library provides another route to the same work.
@@ -64,3 +68,16 @@ Manual: Find the task’s output through search and grouping, open its stack, pa
- A local path is not automatically an uploaded artifact accessible to another user.
- A preview screenshot is not proof that download bytes or revision references are correct.
- Version conflicts and stale annotations must stay visible rather than silently targeting different content.
### Storybook verification
#### `documents`
Scope: ui
Storybook: Writable/read-only document, save pending/failure/conflict, revision history/historical preview and restore confirmation.
Production: Persist edited body and reload; append-only restore creates new revision; reject stale writes and inaccessible company/task.
Sources: Source: [IssueDocumentsSection.tsx](../../ui/src/components/IssueDocumentsSection.tsx), [TaskDocumentPanel.tsx](../../ui/src/components/task-side-panel/TaskDocumentPanel.tsx), [documents.ts](../../server/src/services/documents.ts). Tests: [IssueDocumentsSection.test.tsx](../../ui/src/components/IssueDocumentsSection.test.tsx), [document-revisions.test.ts](../../ui/src/lib/document-revisions.test.ts), [documents-service.test.ts](../../server/src/__tests__/documents-service.test.ts), [issue-document-restore-routes.test.ts](../../server/src/__tests__/issue-document-restore-routes.test.ts)
### Documentation scope: Artifacts and work products
Document/attachment/library/work-product journeys are mapped; every media preview type, storage backend, annotation conflict, and runtime-resource lifecycle variant remains separate.
maps/feature-map/execution-environments.md
+35 -1
View File
@@ -1,4 +1,8 @@
# Local, SSH, and sandbox environments
---
navigation: {"section":"Projects and execution","sectionOrder":40,"order":40}
---
# Execution environments
Operators configure where agents execute, probe readiness, select an environment for work, and inspect remote provisioning or custom-image state when the installed provider supports it.
@@ -82,3 +86,33 @@ Manual: Run a bounded command in the intended target, inspect its output and wor
harness; the selected native runtime still needs its own setup and useful-task proof.
- The local option may appear only when editing an existing local environment; availability follows current UI/provider capabilities.
- Workspace service reachability and environment reachability are separate checks.
### Storybook verification
#### `configuration`
Scope: ui
Storybook: Local/SSH/sandbox editors; unavailable providers, missing credentials, save pending/error and restricted operator.
Production: Persist target configuration and enforce instance-admin/local-operator mutation boundary; target catalog is instance-scoped.
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environments.ts](../../server/src/routes/environments.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-service.test.ts](../../server/src/__tests__/environment-service.test.ts)
#### `capabilities`
Scope: ui
Storybook: Supported versus unavailable driver/provider controls and interactive-setup/template-capture limitations.
Production: Verify advertised driver/plugin capabilities match operations; unavailable provider cannot become working target; capability discovery must not allocate sandbox.
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environments.ts](../../ui/src/api/environments.ts). Tests: [environment-capability-contract.test.ts](../../server/src/__tests__/environment-capability-contract.test.ts), [environment-execution-target-capabilities.test.ts](../../server/src/__tests__/environment-execution-target-capabilities.test.ts), [plugin-environment-driver-sandbox-capabilities.test.ts](../../server/src/__tests__/plugin-environment-driver-sandbox-capabilities.test.ts)
#### `probe`
Scope: ui
Storybook: Remote Test pending, success, reachability/auth failure and platform qualification absent/invalidated notice.
Production: Probe actual owned target; verify selected saved immutable config/image/company qualification plus lease cleanup; local API probe proves host/cwd only and has no UI Test button.
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environment-probe.ts](../../server/src/services/environment-probe.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-probe.test.ts](../../server/src/__tests__/environment-probe.test.ts), [environment-live-ssh.test.ts](../../server/src/__tests__/environment-live-ssh.test.ts)
#### `images`
Scope: ui
Storybook: Custom-image setup/capture/progress, terminal connect/disconnect/failure, unsupported capability and active-image drift.
Production: Execute owned provider setup/capture/probe/terminal transport with correct saved image identity, authority, cleanup and shutdown; terminal screenshot cannot prove operation.
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environment-custom-images.ts](../../server/src/services/environment-custom-images.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-custom-images-service.test.ts](../../server/src/__tests__/environment-custom-images-service.test.ts)
maps/feature-map/gateways-profiles.md
+13
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":40}
---
# Tool gateways and access profiles
Administrators expose selected tools through gateways and reusable access profiles, connect clients, manage tokens, and inspect gateway activity.
@@ -50,3 +54,12 @@ Manual: Create a bounded profile, choose its offered tools and options, save or
- A copied endpoint is not proof of client authentication or tool discovery.
- Gateway access cannot replace underlying connection/action permission checks.
- Advanced tool routes require the appropriate admin gate; legacy tool URLs may redirect.
### Storybook verification
#### `tokens`
Scope: ui
Storybook: Mount current TokensPanel with issue controls, once-only token reveal, expiry/actions, revocation confirmation and failures. Old GatewaysTab fixtures and assistant OAuth revocation are insufficient.
Production: Issue bounded token via POST /tool-gateway/gateways/{id}/tokens; call allowed and excluded tools; revoke via /tool-gateway/gateway-tokens/{id}/revoke and verify denial using same client.
Sources: Source: [TokensPanel.tsx](../../ui/src/pages/apps/gateways/panels/TokensPanel.tsx), [tool-gateway.ts](../../server/src/routes/tool-gateway.ts), [tools.ts](../../ui/src/api/tools.ts). Tests: [TokensPanel.test.tsx](../../ui/src/pages/apps/gateways/panels/TokensPanel.test.tsx), [tool-gateway-service.test.ts](../../server/src/__tests__/tool-gateway-service.test.ts), [tool-gateway.test.ts](../../server/src/__tests__/tool-gateway.test.ts)
maps/feature-map/goals.md
+24
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Projects and execution","sectionOrder":40,"order":20}
---
# Goals and work alignment
People define company and lower-level goals and connect projects and tasks to the outcome they serve.
@@ -47,3 +51,23 @@ Manual: Compare a task with an explicit goal to one relying on project context.
- A goal status is not an independently measured proof of business success.
- Do not infer a complete goal browser test from the small properties-toggle suite.
### Storybook verification
#### `alignment`
Scope: ui
Storybook: Project/task goal selection, explicit/inherited context and invalid association error.
Production: Persist same-company valid association, reject invalid/cross-company reference, verify explicit versus inherited server context after reload.
Sources: Source: [ProjectProperties.tsx](../../ui/src/components/ProjectProperties.tsx), [GoalDetail.tsx](../../ui/src/pages/GoalDetail.tsx). Tests: [project-goal-validation.test.ts](../../server/src/__tests__/project-goal-validation.test.ts), [issues-goal-context-routes.test.ts](../../server/src/__tests__/issues-goal-context-routes.test.ts), [issue-goal-fallback.test.ts](../../server/src/__tests__/issue-goal-fallback.test.ts), [project-goal.test.ts](../../cli/src/__tests__/project-goal.test.ts)
#### `navigation`
Scope: ui
Storybook: Parent/child goal and project/task context links, empty/unavailable context and permitted destination.
Production: Follow actual goal/project/task records and compare explicit versus inherited context; ensure reload and inaccessible destination behavior.
Sources: Source: [GoalDetail.tsx](../../ui/src/pages/GoalDetail.tsx), [GoalProperties.tsx](../../ui/src/components/GoalProperties.tsx). Tests: [GoalDetail.test.tsx](../../ui/src/pages/GoalDetail.test.tsx), [issues-goal-context-routes.test.ts](../../server/src/__tests__/issues-goal-context-routes.test.ts), [issue-goal-fallback.test.ts](../../server/src/__tests__/issue-goal-fallback.test.ts)
### Documentation scope: Goals, dashboards, costs, and activity
Core goal/report/budget/audit journeys are mapped. Every aggregation/filter combination, cost source, and overlapping budget window still needs dedicated cases.
maps/feature-map/inbox-search.md
+58
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":30}
---
# Inbox, decisions, and search
People find work that needs their attention, distinguish unread activity from required decisions, archive handled items, and search across the company.
@@ -12,6 +16,7 @@ Agent access: [companion](../agent-access-map/inbox-search.md).
- `triage`: read or archive attention items without pretending the underlying task is complete.
- `decisions`: open the source of a decision and act in the right context.
- `search`: query company work and follow a result to its original record.
- `toasts`: receive live task notifications only for personal participation or explicit mentions.
## How to get to it (user POV)
@@ -27,6 +32,11 @@ Open `/decisions`, then a queue at `/decisions/queues/:key` and its source item.
Open `/search` or the navigation search entry.
### `toasts`
Keep a company page open while another person or agent updates a task.
See [toast semantics](../../doc/TOASTS.md) for eligibility and suppression rules.
## Driving it with Playwright and the Paperclip CLI
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Seed assigned, unread, blocked, and resolved tasks plus a pending decision. Record the combined Inbox/Tasks experimental setting.
@@ -40,6 +50,8 @@ cover exclusion of historical automatic read cleanup from user participation,
unread counts, and activity timestamps while retaining explicit user decisions
and audit history.
Manual: Seed a scheduled routine execution owned by the current human. It stays out of Mine until an existing participation rule admits it. Verify comments, assignment, and manual routine runs admit automated tasks while reading alone does not. Inbox discovery and Blocked hide unrelated automation by default; the **show agent-created tasks** checkbox reveals it without subscribing the user. Reload and verify membership, unread badges, archive/resurfacing, and preference persistence.
Manual: Read an unread task, return to Unread, archive a handled item, and reload. Verify personal triage state changes while task status stays correct. Switch users and companies to check isolation.
Seed a completed task whose only activity under the viewing user is automatic
@@ -60,8 +72,38 @@ Automated: [search page](../../ui/src/pages/Search.test.tsx) and [company search
Manual: Search a unique task title and content phrase, open the result, and compare the actual record. Test filters, no results, and a second company. Verify stale results do not expose inaccessible data.
### `toasts`
Automated: [persisted eligibility](../../server/src/__tests__/task-toast-eligibility.test.ts)
checks creation, assignment, comments, mentions, deliberate edits, excluded read
activity, company isolation, local-board, and persisted run-task attribution.
[Socket delivery](../../server/src/__tests__/live-events-toast.test.ts) checks
viewer-specific projection; [UI delivery](../../ui/src/context/LiveUpdatesProvider.hook.test.tsx)
checks eligibility gating, cache updates, stale callbacks, and existing suppression.
[UI cache handling](../../ui/src/context/LiveUpdatesProvider.test.ts) checks visible
comment refresh when authenticated events omit hydration metadata.
The `task toasts follow personal involvement in multiplayer` case in the
[authenticated browser suite](../../tests/e2e/multi-user-authenticated.spec.ts)
exercises quiet unrelated updates, read-only visits, first/historical mentions,
self-activity, and visible-task suppression against persisted data.
Manual: Use two authenticated browser sessions in the same isolated company.
Create separate tasks for each person and use one shared agent. From a company
task list, verify that the other person's unrelated task updates produce no
toast but still refresh the list. Comment on one of their tasks, then have them
update it: a toast should appear. Repeat using assignment, a deliberate edit,
and a first explicit user mention in a comment or description. Reload before a
later update to prove eligibility does not depend on browser history. Mere
viewing, agent ownership, responsible-user attribution, and parent participation
must remain quiet. Task-linked failures follow the same participation rule;
generic agent errors remain quiet. Repeat while viewing the relevant task and
after switching company/account to verify suppression and isolation.
## Gotchas
- Notifications do not grant task access or change Mine membership.
- A feature-map recipe and mocked UI tests do not prove live multiplayer behavior.
- Combined Inbox/Tasks requires both `enableCombinedInboxTasks` and
`enableStreamlinedUi`. [Standalone Inbox tests](../../ui/src/pages/Inbox.test.tsx)
render archive/read controls and toolbars; this is not live multi-user evidence.
@@ -69,3 +111,19 @@ Manual: Search a unique task title and content phrase, open the result, and comp
- Personal archival is not task cancellation or completion.
- Legacy Inbox routes can redirect to the combined task view; record which host actually rendered.
- Search service tests do not establish the relevance quality of every query.
### Storybook verification
#### `views`
Scope: ui
Storybook: Mine/Recent/Unread/Blocked and broader task views; combined versus standalone host; loading/empty/error/filter states.
Production: Use persisted personal participation/read data; verify scoped counts and list navigation/reload; automatic read cleanup must not create Mine membership.
Sources: Source: [Inbox.tsx](../../ui/src/pages/Inbox.tsx), [Issues.tsx](../../ui/src/pages/Issues.tsx). Tests: [Inbox.test.tsx](../../ui/src/pages/Inbox.test.tsx), [Issues.test.tsx](../../ui/src/pages/Issues.test.tsx), [issues-service.test.ts](../../server/src/__tests__/issues-service.test.ts)
#### `toasts`
Scope: ui
Storybook: Eligible live task toast, explicit mention, quiet unrelated event, own-action/visible-task suppression, dedupe and company/account switch.
Production: Persisted participation and mentions determine per-viewer socket eligibility; quiet events still refresh caches; reload retains eligibility, unauthorized resources remain denied.
Sources: Source: [ToastViewport.tsx](../../ui/src/components/ToastViewport.tsx), [ToastContext.tsx](../../ui/src/context/ToastContext.tsx), [LiveUpdatesProvider.tsx](../../ui/src/context/LiveUpdatesProvider.tsx), [task-toast-eligibility.ts](../../server/src/realtime/task-toast-eligibility.ts). Tests: [ToastContext.test.tsx](../../ui/src/context/ToastContext.test.tsx), [ToastViewport.test.tsx](../../ui/src/components/ToastViewport.test.tsx), [LiveUpdatesProvider.hook.test.tsx](../../ui/src/context/LiveUpdatesProvider.hook.test.tsx), [task-toast-eligibility.test.ts](../../server/src/__tests__/task-toast-eligibility.test.ts), [live-events-toast.test.ts](../../server/src/__tests__/live-events-toast.test.ts), [multi-user-authenticated.spec.ts](../../tests/e2e/multi-user-authenticated.spec.ts)
maps/feature-map/instance-operations.md
+34 -1
View File
@@ -1,4 +1,8 @@
# Installation, configuration, updates, and backups
---
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":40}
---
# Instance operations
An operator can install and run Paperclip, diagnose the instance, configure supported deployment settings, manage its service, and produce a recoverable database backup.
@@ -34,6 +38,12 @@ Automated: [doctor](../../cli/src/__tests__/doctor.test.ts), [update command](..
Manual: Inspect the selected installation/channel and configuration, start the isolated instance, confirm health and browser access, then stop that instance. For update changes, use the dry-run/check path first and verify installed version and rollback state on an owned disposable installation.
Routine HTTP monitoring may use `GET /api/liveness` (or `HEAD`). It returns only
process startup status and the public build commit without SQL or authentication.
It remains reachable during an idle drain. Use `/api/health` for explicit database
readiness, signed bootstrap, and authorized diagnostics; liveness does not
establish database health or claim a workspace.
### `settings-backup`
Automated: [experimental settings](../../ui/src/pages/InstanceExperimentalSettings.test.tsx) and [database backup routes](../../server/src/__tests__/instance-database-backups-routes.test.ts) cover their UI/API contracts.
@@ -50,3 +60,26 @@ Manual: Change a harmless experimental setting, reload, and confirm the affected
- A successful backup write does not prove restoration works.
- Settings visibility and mutability differ for cloud-managed and self-hosted instances.
- Keep the three data paths distinct: first-party Telemetry, operator-configured OpenTelemetry, and local run logs.
### Storybook verification
#### `backup`
Scope: ui
Storybook: Mount shipped InstanceGeneralSettings in CompanySettings with daily/weekly/monthly retention presets, selected values, saving/error/loading and cloud-hidden controls. Backup creation and restore remain separate CLI/operator checks.
Production: PATCH /api/instance/settings/general must enforce instance settings authority and managed hidden fields, persist retention and survive reload. Separately inspect a real backup and restore a known record into a second disposable target; a successful write does not prove restoration.
Sources: Source: [InstanceGeneralSettings.tsx](../../ui/src/pages/InstanceGeneralSettings.tsx), [CompanySettings.tsx](../../ui/src/pages/CompanySettings.tsx), [instance-settings.ts](../../server/src/routes/instance-settings.ts), [db-backup.ts](../../cli/src/commands/db-backup.ts). Tests: [InstanceGeneralSettings.test.tsx](../../ui/src/pages/InstanceGeneralSettings.test.tsx), [instance-settings-routes.test.ts](../../server/src/__tests__/instance-settings-routes.test.ts), [instance-settings-managed-overlay.test.ts](../../server/src/__tests__/instance-settings-managed-overlay.test.ts), [instance-database-backups-routes.test.ts](../../server/src/__tests__/instance-database-backups-routes.test.ts)
#### `install-update`
Scope: cli
Storybook: No authored story required for install, channel selection, update or rollback command execution.
Production: Use an owned managed installation: check/dry-run, installed version, retained payload rollback and failure. Source-checkout guidance is a separate case; rollback does not undo database migrations.
Sources: Source: [index.ts](../../cli/src/index.ts), [install.ts](../../cli/src/commands/install.ts), [update.ts](../../cli/src/commands/update.ts). Tests: [install-command.test.ts](../../cli/src/__tests__/install-command.test.ts), [update-command.test.ts](../../cli/src/__tests__/update-command.test.ts)
#### `diagnostics`
Scope: cli
Storybook: No authored story required for doctor/health command results.
Production: Run doctor against an owned data directory; check readiness and nonzero failures. A listening port alone does not prove readiness; repair requires observing the repaired result.
Sources: Source: [doctor.ts](../../cli/src/commands/doctor.ts). Tests: [doctor.test.ts](../../cli/src/__tests__/doctor.test.ts)
maps/feature-map/navigation-preferences.md
+20
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":30}
---
# Navigation, profile, and announcements
People organize their sidebar, move between company resources, maintain their profile, and dismiss product announcements with the correct persistence and identity scope.
@@ -50,3 +54,19 @@ Manual: Change a disposable user’s display details, reload, and inspect an att
- Announcement dismissals are intentionally instance-wide user preferences, unlike company-scoped domain data.
- Legacy/production shells need their own navigation check when affected.
- A route redirect is part of the journey; do not document a removed screen as if it still renders.
### Storybook verification
#### `preferences`
Scope: ui
Storybook: Mount Sidebar using real preference boundary with stars/order/collapse/recents state. Clearly distinguish in-memory section collapse, browser-local recents and server-saved stars/order.
Production: GET/PUT /sidebar-preferences/me and /companies/{id}/sidebar-preferences/me plus stars must retain intended user/company isolation across reload and switch. Section collapse reopens after reload; global collapse is disabled.
Sources: Source: [Sidebar.tsx](../../ui/src/components/Sidebar.tsx), [sidebar-preferences.ts](../../server/src/routes/sidebar-preferences.ts), [sidebar-preferences.ts](../../server/src/services/sidebar-preferences.ts). Tests: [Sidebar.test.tsx](../../ui/src/components/Sidebar.test.tsx), [sidebar-preferences-routes.test.ts](../../server/src/__tests__/sidebar-preferences-routes.test.ts)
#### `fallbacks`
Scope: browser
Storybook: A NotFound rendering story can help polish, but missing-resource/legacy-deep-link capability principally needs real App/router/browser scenarios preserving company and query intent.
Production: Cold-open invalid company/resource and retired URL; verify explicit fallback or correct canonical redirect without silently targeting a different resource/company.
Sources: Source: [NotFound.tsx](../../ui/src/pages/NotFound.tsx), [App.tsx](../../ui/src/App.tsx), [company-routes.ts](../../ui/src/lib/company-routes.ts). Tests: [App.activity-routing.test.tsx](../../ui/src/App.activity-routing.test.tsx), [App.cases-routing.test.tsx](../../ui/src/App.cases-routing.test.tsx), [App.test.tsx](../../ui/src/App.test.tsx), [company-routes.test.ts](../../ui/src/lib/company-routes.test.ts)
maps/feature-map/onboarding.md
+81
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Getting started and access","sectionOrder":10,"order":10}
---
# Onboarding and first work
An operator can start an instance, create a company, configure its first agent, and reach a real first task. Instance setup and company onboarding are separate steps.
@@ -56,6 +60,10 @@ also permits Legacy. Do not switch runners after onboarding when claiming proof
of that default. Test the selected runtime and account, then complete a bounded
useful task and follow-up with an independently checked file artifact. Saved
execution configuration and recorded run identity must match after reload.
The Codex first-task eval applies operator QA bounds before Get started through
the existing agent configuration API. It verifies that only timeout and
concurrency change; automatic runner, account and environment choices remain.
These campaign bounds are separate from production creation defaults.
Use [runner validation](./runs-adapters.md#adapter-setup) and
[environment qualification](./execution-environments.md#environment-settings)
for the prerequisites; a successful login alone is insufficient.
@@ -70,6 +78,48 @@ test or hire. Named snapshots and mutable image tags do not gain qualification
through this flow. [Helper controls](../../ui/src/lib/qualify-claude-setup.test.ts)
and mounted wizard/new-agent tests use mocks; live managed acceptance remains a
separate gate.
For a new Codex agent with Auto on a saved immutable OCI sandbox, Connect first
uses the existing saved environment probe when authoritative qualification is
absent. The board actor needs the existing instance-environment administration
permission. Refresh company/environment-scoped discovery before testing the
selected runtime. A denied probe, unconfirmed cleanup or setup failure must be
visible; selecting Legacy remains an explicit choice. Creation and discovery
themselves allocate no target. A valid measured unsupported target follows the
server's Legacy default. Named Cloud snapshots remain a separate unqualified
boot-identity and fresh-signup gap.
Selected native setup derives its target isolation as task execution does. The
hello probe retains its read-only permission profile, approval-never policy and
bounded provider turn. It skips Codex's project-instruction discovery in its new,
empty private workspace; ordinary tasks still load their project instructions.
Local and SSH transports retain Codex isolation. An injected environment flag
cannot establish an outer sandbox identity. Verify these boundaries with the
existing native setup controls and a real managed task/follow-up; source checks
alone are insufficient.
The explicit manual Product E2E cell
`confirmation-replies.runner-codex.daytona.task-card-accept` covers this fresh
managed wizard path without fixture agent creation or a fixture preprobe. Its
existing attachment oracle checks a downloaded physical file and follow-up
continuity. Setup evidence must correlate both lease IDs with the same company,
environment and provider; missing responses or unmatched rows keep cost coverage
unknown. Run this cell only on an eligible target with separately authorized
provider, runtime and cleanup reservations. Its source and mock controls are
prepared. The literal `ea6c8eb5e16d61111968f633a66748b397b64a3e` live attempt
failed: the child document existed, but the physical file was attached to the
parent, and recovery stopped the completion callback before a provider turn.
The failed report remains evidence; the revised source still needs live proof.
Local cases and automatic selection remain unchanged.
For accepted file-producing work, verify exactly one self-assigned child with a
self-contained description. The onboarding run must yield through the existing
dependency/block disposition so the child's own execution can publish its file.
Native file registration remains bound to the executing task. On completion,
the original conversation must receive the actual child and downloadable file
links. Document-only child work may finish inline; a plan-only request must not
start implementation. Existing first-task asset controls check the instructions,
not model compliance. Inspect the child's execution, document, downloaded file
and source-correlated completion reply in the real journey.
Leave and resume during harness/runner setup. Confirm the draft retains the
explicit choice and compatible account bindings, old native Codex setup links
@@ -77,6 +127,17 @@ recover the harness and runner, and a changed harness or runner invalidates stal
test results. Existing Legacy agents remain Legacy when their onboarding/setup
configuration is reopened; this journey does not migrate them.
Reload both `/onboarding` and the company-prefixed route after the first agent is
saved but before Get started. The authorized draft must retain its current step
and that agent's execution choice. An explicit new-company opening still starts
fresh. Opening another company must clear the previous company's resource IDs;
an unauthorized account must not restore its draft. Existing component controls
cover these boundaries; they do not substitute for the managed first-task eval.
The existing mocked-login browser case reopens and reloads Connect directly. It
checks the saved company/name/harness/runner, exact active authorization session,
one login start and no hire while login is pending. This is login UI evidence,
not a provider or managed-environment qualification.
### `cli-setup`
Automated: [CLI onboarding](../../cli/src/__tests__/onboard.test.ts) and [isolated test drive](../../cli/src/__tests__/test-drive.test.ts) cover their setup contracts; they do not establish that every model account is usable.
@@ -88,3 +149,23 @@ Manual: Run setup in the disposable directory, open the URL it prints, and confi
- An empty company, an empty instance, and an unauthenticated browser are different states.
- Creating an agent does not prove its provider login or first execution succeeded.
- See [access](./access.md) for authenticated deployments and [agents](./agents.md) for later hiring.
### Storybook verification
#### `resume`
Scope: ui
Storybook: Restored incomplete wizard; invalid or unauthorized saved company; temporarily withheld draft; account switch; storage failure.
Production: Reload company-prefixed onboarding without duplicating company; restore only authorized account/company draft and retain input after recoverable loading failure.
Sources: Source: [OnboardingWizard.tsx](../../ui/src/components/OnboardingWizard.tsx), [onboarding-state.ts](../../ui/src/lib/onboarding-state.ts). Tests: [OnboardingWizard.test.tsx](../../ui/src/components/OnboardingWizard.test.tsx), [onboarding-state.test.ts](../../ui/src/lib/onboarding-state.test.ts), [onboarding.spec.ts](../../tests/e2e/onboarding.spec.ts)
#### `instance`
Scope: cli
Storybook: No authored UI story required for host installation and startup.
Production: Configure isolated data directory, start instance, confirm printed URL/identity/health, restart with saved configuration.
Sources: Source: [onboard.ts](../../cli/src/commands/onboard.ts), [onboard-service.ts](../../cli/src/onboard-service.ts). Tests: [onboard.test.ts](../../cli/src/__tests__/onboard.test.ts), [onboard-service.test.ts](../../cli/src/__tests__/onboard-service.test.ts), [test-drive.test.ts](../../cli/src/__tests__/test-drive.test.ts)
### Documentation scope: Login, invitations, and access
Deployment modes and core login/invite/member/token paths are mapped; exhaustive identity-provider, expiry, role, and resource-policy combinations remain.
maps/feature-map/pipelines.md
+34
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Automation and structured work","sectionOrder":60,"order":20}
---
# Pipelines, review queues, and learnings
With the pipeline experiment enabled, people move structured work through configured stages, inspect stage automation, review outputs, and retain learning records.
@@ -48,3 +52,33 @@ Manual: Open a pending review, inspect its source output and revision, accept or
- These routes are experimental and may redirect or deny access when disabled.
- ReviewQueue and Learnings are hosted from the pipeline module; a page-file inventory alone misses them.
- Pipeline items and free-standing [cases](./cases.md) share records but have different navigation contexts.
### Storybook verification
#### `stages`
Scope: ui
Storybook: Mount PipelineSettings ordered stages, automation assignees/env, invalid transitions, unsaved state, saving and failed save.
Production: POST/PATCH stages and PUT /pipelines/{id}/transitions must persist valid order/configuration, enforce ownership and reject invalid transitions; actual automation execution remains separate.
Sources: Source: [PipelineSettings.tsx](../../ui/src/pages/PipelineSettings.tsx), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [PipelineSettings.test.ts](../../ui/src/pages/PipelineSettings.test.ts), [pipelines-service.test.ts](../../server/src/__tests__/pipelines-service.test.ts), [pipelines-routes.test.ts](../../server/src/__tests__/pipelines-routes.test.ts)
#### `items`
Scope: ui
Storybook: Mount Pipelines/PipelineItemDetailView board grouping, item creation/details, stage/health/work references, empty/loading and failed transition.
Production: GET/POST /pipelines/{id}/cases and POST /cases/{id}/transition must maintain company scope, valid stage changes and linked work; fixture stage state does not prove automation.
Sources: Source: [Pipelines.tsx](../../ui/src/pages/Pipelines.tsx), [PipelineWorkReferences.tsx](../../ui/src/components/PipelineWorkReferences.tsx), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [Pipelines.test.tsx](../../ui/src/pages/Pipelines.test.tsx), [pipelines-service.test.ts](../../server/src/__tests__/pipelines-service.test.ts), [pipelines-routes.test.ts](../../server/src/__tests__/pipelines-routes.test.ts), [pipelines-tutorial-flow.spec.ts](../../tests/e2e/pipelines-tutorial-flow.spec.ts)
#### `review`
Scope: ui
Storybook: Mount ReviewQueue and item review pending output/revision, accept/reject/request-changes, bulk selection, stale/conflicting submission and errors.
Production: POST /cases/{id}/review and /companies/{id}/review-cases/bulk must authorize reviewer, persist correct outcome/transition and reject stale or invalid input.
Sources: Source: [Pipelines.tsx](../../ui/src/pages/Pipelines.tsx), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [Pipelines.test.tsx](../../ui/src/pages/Pipelines.test.tsx), [pipelines-routes.test.ts](../../server/src/__tests__/pipelines-routes.test.ts), [pipelines-service.test.ts](../../server/src/__tests__/pipelines-service.test.ts), [pipelines-tutorial-flow.spec.ts](../../tests/e2e/pipelines-tutorial-flow.spec.ts)
#### `learnings`
Scope: ui
Storybook: Mount actual Learnings export with filtered case events, review/forced-move entries, source links, empty/loading/error. This is event history, not a separately authored learning-record system.
Production: GET /companies/{id}/case-events in pipelines routes needs existing company/access contract tests; a rendered event cannot establish learning quality.
Sources: Source: [Pipelines.tsx](../../ui/src/pages/Pipelines.tsx), [pipeline-learnings.ts](../../ui/src/lib/pipeline-learnings.ts), [pipelines.ts](../../server/src/routes/pipelines.ts). Tests: [Pipelines.test.tsx](../../ui/src/pages/Pipelines.test.tsx), [pipelines-routes.test.ts](../../server/src/__tests__/pipelines-routes.test.ts), [pipelines-service.test.ts](../../server/src/__tests__/pipelines-service.test.ts)
maps/feature-map/plugins.md
+39 -1
View File
@@ -1,4 +1,8 @@
# Plugins and contributed product surfaces
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":60}
---
# Plugins
Operators install and configure plugins, inspect their status and errors, and use their contributed pages, tools, and managed resources within the plugin’s granted capabilities.
@@ -49,3 +53,37 @@ Manual: Open the contributed page by navigation and cold deep link, perform a ha
- Installing a plugin does not authorize every host capability or external action.
- Plugin-provided routes are dynamic; this map covers the host lifecycle, not every third-party feature.
- Environment-driver plugins also need the [environment](./execution-environments.md) checks.
### Storybook verification
#### `installation`
Scope: ui
Storybook: Mount PluginManager trusted package and bundled-local choices, pending install, validation/recoverable error and installed status.
Production: POST /plugins/install on a disposable package; enforce instance install authority, trusted path/package validation and correct version. Package and local install are distinct.
Sources: Source: [PluginManager.tsx](../../ui/src/pages/PluginManager.tsx), [plugins.ts](../../server/src/routes/plugins.ts), [plugin-install-guard.ts](../../server/src/services/plugin-install-guard.ts). Tests: [plugin-install-route-security.test.ts](../../server/src/__tests__/plugin-install-route-security.test.ts), [plugin-install-autobuild.test.ts](../../server/src/__tests__/plugin-install-autobuild.test.ts), [plugin-routes-authz.test.ts](../../server/src/__tests__/plugin-routes-authz.test.ts)
#### `configuration`
Scope: ui
Storybook: Mount PluginSettings valid/invalid schema inputs, saved configuration, pending/failure and unavailable plugin.
Production: GET/POST /plugins/{id}/config and POST config/test must preserve validation/company scope and deliver saved config to real plugin worker/startup.
Sources: Source: [PluginSettings.tsx](../../ui/src/pages/PluginSettings.tsx), [plugins.ts](../../server/src/routes/plugins.ts), [plugin-config-validator.ts](../../server/src/services/plugin-config-validator.ts). Tests: [PluginSettings.test.tsx](../../ui/src/pages/PluginSettings.test.tsx), [plugin-config-startup-delivery.test.ts](../../server/src/__tests__/plugin-config-startup-delivery.test.ts), [plugin-routes-authz.test.ts](../../server/src/__tests__/plugin-routes-authz.test.ts)
#### `contributions`
Scope: ui
Storybook: Mount PluginPage and CompanySettingsPluginPage contributed routes/tabs, loading, missing/unavailable plugin and action failures with a known fixture plugin.
Production: Serve real static plugin UI; enforce bridge data/action host capabilities and company boundaries; exercise a harmless action and cold deep link.
Sources: Source: [PluginPage.tsx](../../ui/src/pages/PluginPage.tsx), [CompanySettingsPluginPage.tsx](../../ui/src/pages/CompanySettingsPluginPage.tsx), [plugins.ts](../../server/src/routes/plugins.ts), [plugin-ui-static.ts](../../server/src/routes/plugin-ui-static.ts). Tests: [PluginPage.test.tsx](../../ui/src/pages/PluginPage.test.tsx), [CompanySettingsPluginPage.test.tsx](../../ui/src/pages/CompanySettingsPluginPage.test.tsx), [plugin-ui-static.test.ts](../../server/src/__tests__/plugin-ui-static.test.ts), [plugin-tenant-isolation.test.ts](../../server/src/__tests__/plugin-tenant-isolation.test.ts)
#### `lifecycle`
Scope: ui
Storybook: Mount PluginManager active/disabled/uninstall/upgrade pending and failures; distinguish operator controls from developer watcher reload.
Production: POST enable/disable and DELETE /plugins/{id} must stop worker/tool/managed-resource activity and clean owned resources; verify disposable restart/uninstall and developer watcher separately.
Sources: Source: [PluginManager.tsx](../../ui/src/pages/PluginManager.tsx), [plugins.ts](../../server/src/routes/plugins.ts), [plugin-lifecycle.ts](../../server/src/services/plugin-lifecycle.ts), [plugin-dev-watcher.ts](../../server/src/services/plugin-dev-watcher.ts). Tests: [plugin-lifecycle-restart.test.ts](../../server/src/__tests__/plugin-lifecycle-restart.test.ts), [plugin-routes-authz.test.ts](../../server/src/__tests__/plugin-routes-authz.test.ts), [plugin-dev-watcher.test.ts](../../server/src/__tests__/plugin-dev-watcher.test.ts)
### Documentation scope: Plugins, gateways, and tool profiles
Host plugin/gateway/profile lifecycles are mapped. Third-party plugin behaviors and every client transport/provider combination are outside host-wide coverage.
maps/feature-map/projects.md
+16
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Projects and execution","sectionOrder":40,"order":10}
---
# Projects and repositories
People group tasks into projects, attach goals and repositories, and configure the context and defaults used by project work.
@@ -51,3 +55,15 @@ Manual: Attach a small repository, save, and create a project task. Inspect the
- Project repository configuration and a provisioned execution workspace are different records.
- See [workspaces](./workspaces.md), [goals](./goals.md), and [budgets](./budgets-costs.md) for those features.
- Do not assume a deleted or archived project should erase its historical task evidence.
### Automatic repository skills
Creating or attaching a GitHub repository enqueues skill import without another setup
step. Check Skills → Sources and the installed library afterward. Ordinary edits to
older projects do not adopt their repositories; explicit adoption belongs in Sources.
Removing a repository retains installed skills and originating project access but stops
its automatic tracking. Changing the ref does not retarget existing skill references.
### Documentation scope: Projects and execution workspaces
Provider-specific provisioning, multi-repository/submodule edge cases, Git reconciliation variants, and all service exposure combinations require deeper recipes.
maps/feature-map/questions-and-approvals.md
+8
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":50}
---
# Questions and approvals
People answer an agent's questions and decide requests without losing the task's
@@ -182,3 +186,7 @@ unless its actual provider journey was driven.
sharing UI. A watchdog cannot acquire board authority by resolving a card.
- An answer to an old question can queue behind a successor run; it does not
automatically steer that run. See [steering](./steering.md).
### Documentation scope: Formal governance approvals
Formal board decisions and signoff have recipes; every approval payload/type and actor/host error permutation is not enumerated.
maps/feature-map/recovery.md
+84 -1
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Projects and execution","sectionOrder":40,"order":50}
---
# Recovery
People can see why a task stopped, who owns the next action, and whether a safe
@@ -98,6 +102,17 @@ cleanup. The [route regressions](../../server/src/__tests__/issue-recovery-actio
and [heartbeat regression](../../server/src/__tests__/heartbeat-process-recovery.test.ts)
cover this sequence without a live operator recovery claim.
An intentionally Done onboarding parent can still need its validated
child-completion report. Recovery must not mark that callback successful before
execution solely because the parent is Done. The existing
[stale-lock sweep suite](../../server/src/__tests__/recovery-stale-issue-lock-sweep.test.ts)
covers delayed native/Legacy startup, invalid parent/child/company/assignee
bindings and a dead owner. Process-death and ownership backstops remain active.
Repeat the real onboarding journey and correlate callback turn events with its
reply and downloadable child file; status alone does not prove delivery. The
literal `ea6c8eb5e16d61111968f633a66748b397b64a3e` live failure is retained,
and the revised behavior still needs live qualification.
### `run-detail`
Automated: [run workspace recovery](../../ui/src/components/RunWorkspaceRecoverySurface.test.tsx)
@@ -119,7 +134,41 @@ Automated: [disposition notices](../../ui/src/components/DispositionRecoveryNoti
tests pending/error/gated states and waiting for the real retry acknowledgement.
The recovery-card suite covers workspace divergence, reissue, reconcile, and
confirmation. [Workspace export](../../ui/src/components/WorkspaceExportRecovery.test.tsx)
covers its separate repair surface.
covers quiet restoration, legacy/operator assistance and resolved states.
For a retained legacy file hold, open the source task after its recovery action
has resolved but its files still need recovery. An authorized board operator can
record the verified recovered files and backup link without changing the current
task status or starting another run. The server must independently validate the
original stopped-execution receipt. Agent Chat must show the file hold rather than
suggesting another message. The [file recovery form](../../ui/src/components/WorkspaceFileRecovery.test.tsx),
[notice](../../ui/src/components/ExecutionBlockerNotice.test.tsx), and
[repair route](../../server/src/__tests__/workspace-restore-repair-route.test.ts)
cover evidence/confirmation, read-only access, stale or missing stop proof,
source-only repair, and preserved task status. These tests use fixtures; separately
verify original files and their attached artifact before recording a real repair.
Repeat source-only repair with a `succeeded` legacy run that still has a retained
file obligation. Its result must remain successful, its current task owner and
status must stay unchanged, and later saved input must become eligible for normal
admission. A running or queued source and a normal retry of a successful turn
remain denied. The [reconciliation regressions](../../server/src/services/workspace-restore-reconciliation.test.ts)
cover these cases and stop-receipt validation without claiming live provider proof.
For an abandoned native copyback owner, the harness verifies the exact stopped
deployment and the reconciler restores saved work automatically. Task users see
no process details or shutdown form. The documented operator API handles older
receipts after independent platform verification, through a separate administrator
gate. The [authorization regressions](../../server/src/__tests__/authorization-service.test.ts)
and [route regressions](../../server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts)
cover administrator admission, ordinary-member and agent denial, suspended and
foreign membership, missing role data, and stale cloud admin rows.
The [native workspace finalizer suite](../../server/src/services/native-runtime/native-workspace-finalizer.test.ts)
runs the real reconciler with a valid saved yield from `result_accepted`,
`workspace_finalizing`, and `retryable_failure`. It verifies physical fencing
before verified stop, automatic and operator recovery, successful export and commitment, hold resolution,
unchanged saved results, retained approval/monitor waits, and no new provider wake.
These local regressions do not prove a deployment platform stopped a foreign writer.
Manual: reproduce an exhausted disposable action. Click once, verify pending
state prevents repeated clicks, and inspect a successful continuation or an
@@ -128,6 +177,17 @@ repair, record the compared branches/revisions and preserve uncommitted work;
confirm the repair's actual result before resuming. Check the denied and stale
action paths. A changed card label is insufficient proof of workspace integrity.
For an abandoned native controller, follow the [stop-verification procedure](../../doc/native-workspace-finalization-recovery.md)
with a disposable deployment. A new platform-bound owner recovers automatically
only after the harness signs proof that the exact deployment fully stopped.
Legacy owners require independently verified stop evidence through the operator
API; the task has no shutdown form. Confirm
the original accepted result commits, the recovery hold resolves, saved files
remain intact, and existing approval waits or monitor checks remain. No new agent
turn should start. Repeat with a retry-phase owner and an ordinary runtime manager;
the first can resume through automatic proof or authorized operator confirmation,
while the second cannot use the operator API.
### `post-stop-message`
Automated: [legacy continuation](../../server/src/services/recovery/legacy-continuation.test.ts),
@@ -167,3 +227,26 @@ only. Separately inspect the underlying execution if it is still stuck.
restart continuity. Use the appropriate runtime suite for that claim.
- See [execution semantics](../../doc/execution-semantics.md) for the governing
recovery contract and [steering](./steering.md) for saved follow-ups.
### Storybook verification
#### `exhaustion`
Scope: ui
Storybook: Exhausted/overdue attempts, operator retry pending/error, blocked authority/gate and specific escalation.
Production: Inspect durable attempt bounds and actual eligible retry/repair; acknowledgment alone does not prove continued execution.
Sources: Source: [IssueRecoveryActionCard.tsx](../../ui/src/components/IssueRecoveryActionCard.tsx), [DispositionRecoveryNotice.tsx](../../ui/src/components/DispositionRecoveryNotice.tsx), [issue-recovery-actions.ts](../../server/src/services/issue-recovery-actions.ts). Tests: [IssueRecoveryActionCard.test.tsx](../../ui/src/components/IssueRecoveryActionCard.test.tsx), [DispositionRecoveryNotice.test.tsx](../../ui/src/components/DispositionRecoveryNotice.test.tsx), [issue-recovery-actions.test.ts](../../server/src/__tests__/issue-recovery-actions.test.ts), [recovery.spec.ts](../../tests/e2e/execution-recovery/recovery.spec.ts)
#### `unknown-outcome`
Scope: ui
Storybook: Uncertain external outcome, required inspection/evidence and explicit permitted operator decision.
Production: Corroborate provider outcome before authorization; enforce no automatic external side-effect replay and reject stale/unauthorized decisions.
Sources: Source: [IssueRecoveryActionCard.tsx](../../ui/src/components/IssueRecoveryActionCard.tsx), [issue-recovery-actions.ts](../../server/src/services/issue-recovery-actions.ts). Tests: [IssueRecoveryActionCard.test.tsx](../../ui/src/components/IssueRecoveryActionCard.test.tsx), [issue-recovery-actions.test.ts](../../server/src/__tests__/issue-recovery-actions.test.ts), [recovery.spec.ts](../../tests/e2e/execution-recovery/recovery.spec.ts)
#### `user-continuation`
Scope: ui
Storybook: Saved follow-up waiting on stop cleanup, pause/budget gate, one eligible continuation and result/failure.
Production: Confirm previous execution stopped before delivery, preserve message, avoid duplicate wakes and honor actual task/ancestor/budget gate in separate legacy/native paths.
Sources: Source: [TaskChatQueuedMessages.tsx](../../ui/src/components/task-chat/TaskChatQueuedMessages.tsx), [legacy-continuation.ts](../../server/src/services/recovery/legacy-continuation.ts), [native-restart-recovery.ts](../../server/src/services/native-runtime/native-restart-recovery.ts). Tests: [legacy-continuation.test.ts](../../server/src/services/recovery/legacy-continuation.test.ts), [native-restart-recovery.test.ts](../../server/src/services/native-runtime/native-restart-recovery.test.ts), [issue-queued-comments-routes.test.ts](../../server/src/__tests__/issue-queued-comments-routes.test.ts), [legacy-failure-continuation.spec.ts](../../tests/e2e/legacy-failure-continuation.spec.ts)
maps/feature-map/routines.md
+29
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Automation and structured work","sectionOrder":60,"order":10}
---
# Routines, schedules, and triggers
Operators define repeatable work, configure its inputs and triggers, run it on demand or automatically, and inspect the execution history and resulting tasks.
@@ -51,3 +55,28 @@ Manual: Set a near-term disposable schedule or authorized test webhook, verify o
- Saving a schedule does not prove the scheduler invoked it.
- Timezone, overlap/concurrency rules, and plugin ownership affect behavior.
- A routine run’s task must still respect pause, access, and budget gates.
- Managed idle hosts may use the [routine wake protocol](../../doc/idle-sleep-safety.md#scheduled-routine-wake-protocol)
to sleep between supported future runs. The host must save a durable alarm
and verify the same generation before stopping. Local execution and catch-up
remain unchanged. Unsupported triggers and other pending work keep it awake.
### Latest skill references
Routine instructions retain stable skill mentions. After a project source syncs an
upstream change, the next execution uses the latest installed version without waiting
on GitHub. Record the resolved version before/after and verify a resumed execution
keeps its original version. Private skill references require current project access
for both the agent and its responsible person.
### Storybook verification
#### `run-now`
Scope: ui
Storybook: Mount RoutineRunVariablesDialog through actual RoutineDetail with required/default inputs, project/workspace overrides, pending, blocked and failed submission. RunButton-only no-op examples do not supply/run inputs.
Production: POST /routines/{id}/run must validate variables, create one attributed execution/task and obey pause/access/budget gates; inspect actual task outcome separately.
Sources: Source: [RoutineRunVariablesDialog.tsx](../../ui/src/components/RoutineRunVariablesDialog.tsx), [RoutineDetail.tsx](../../ui/src/pages/RoutineDetail.tsx), [routines.ts](../../server/src/routes/routines.ts). Tests: [RoutineRunVariablesDialog.test.tsx](../../ui/src/components/RoutineRunVariablesDialog.test.tsx), [routines-service.test.ts](../../server/src/__tests__/routines-service.test.ts), [routines-e2e.test.ts](../../server/src/__tests__/routines-e2e.test.ts)
### Documentation scope: Routines, pipelines, cases, and status cards
All four capabilities have recipes. Trigger/provider/timezone combinations, custom case schemas, stage automation types, and summarizer quality need deeper cases.
maps/feature-map/runs-adapters.md
+45
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Agents and reusable capabilities","sectionOrder":30,"order":20}
---
# Runs, harnesses, and model accounts
Operators choose an agent harness and model account, inspect execution history and transcripts, and distinguish a working configuration from a successful task result.
@@ -45,6 +49,11 @@ and [runtime prerequisites](../../packages/paperclip-runner/README.md) define th
platform/libc boundary. Windows and Alpine/musl remain Legacy. Claude follows
its qualified rollout described above. Disabled adapters, external overrides, and selected-target
qualification also affect availability.
On a fresh forced-Kubernetes instance without an environment row, inspect discovery
and create with automatic selection. Both must retain Legacy without provisioning;
an explicit Paperclip request must give target-qualification guidance. Begin the
ordinary task to exercise the existing lazy environment path. This live journey
remains separate from the resolver's source controls.
For sandbox defaults, follow the [environment probe](./execution-environments.md#environment-settings)
recipe first. Discovery/creation read company-bound immutable-image evidence
@@ -63,6 +72,24 @@ existing agent, make an unrelated edit, and confirm both its persisted runner an
next run stay unchanged. Use [hiring/import preservation](./agents.md#hire-agent)
for approval and portability controls.
Test native Codex with a saved subscription whose setup auth file is a managed
link, as well as a regular file and an API-key account. Setup must seed the
isolated probe from the checked account without exposing credentials or changing
its saved runner. With subscription authentication, an unbound configured
`CODEX_HOME` with linked credentials must fail setup with managed-account or explicit Legacy guidance; it must not claim
readiness when task isolation would omit the file. Dangling or incorrectly owned
credentials must also fail clearly. A selected `CODEX_API_KEY` or
`OPENAI_API_KEY` takes precedence over an unrelated subscription file. Test valid,
dangling and invalid subscription links with that selected key; setup must test
the key without reading or refreshing the unrelated account. The private probe copy must be removed after confirmed retirement following success,
failure or cancellation. Unconfirmed shutdown remains a cleanup failure.
Exercise an unavailable local daemon and a preparation failure before probe
handoff. No owned temporary credential copy may remain, and original account
files must be unchanged. A probe whose shutdown is unconfirmed must retain its
recovery state; do not treat it as a preparation-only failure.
Existing setup controls use fake credentials; real account execution remains
a separate acceptance requirement.
### `run-history`
Automated: [live run routes](../../server/src/__tests__/agent-live-run-routes.test.ts) and [run event sequencing](../../server/src/__tests__/heartbeat-run-event-sequencing.test.ts) cover run data contracts.
@@ -75,6 +102,14 @@ retain their recorded execution configuration; do not infer their runner from a
later edit to the agent. Account/harness branding and execution identity are
different observations, both required in the evidence.
For an onboarding child-completion callback, verify actual session/turn events
and the source-correlated reply. A `succeeded` row alone is insufficient: the
literal `ea6c8eb5e16d61111968f633a66748b397b64a3e` managed attempt was marked
successful during startup without a provider turn. The recovery correction
preserves the existing validated Done-parent handoff; process-death and ownership
checks remain active. Its PostgreSQL controls are separate from the required
revised-source live onboarding and follow-up proof.
## Gotchas
- Model accounts are managed in Apps and inline agent account controls.
@@ -94,3 +129,13 @@ after close. These are lifecycle controls, separate from installed provider proo
The real daemon readiness and recovery controls require their existing native
fixtures in hosted CI; passing credential-free controls does not qualify them.
A primary setup timeout remains a failure even when teardown also fails.
For remote setup shutdown, verify that each durable-state read respects the
remaining suspension deadline. A late result cannot establish suspension or
queue a replacement command after that deadline. An intentional ingress close
must observe physical socket closure before retiring its connection owner and
releasing the endpoint; an unresponsive peer must not extend the setup budget.
The existing transport and ingress suites exercise these conditions without a
provider. Repeat the actual managed setup and useful task journey separately;
the literal `651a3de64fc943216cc414b64b1443809f9499da` Test attempt failed
cleanup before hire and retains its unconfirmed recovery state.
maps/feature-map/secrets.md
+20 -3
View File
@@ -1,4 +1,8 @@
# Secrets, personal credentials, and proposals
---
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":50}
---
# Secrets and proposals
Operators manage company secret references, users supply their own credentials where required, and reviewers decide proposed secret changes without exposing secret values in ordinary UI evidence.
@@ -12,7 +16,7 @@ Agent access: [companion](../agent-access-map/secrets.md).
- `user-secrets`: define required user credentials and set a value for the current user.
- `proposals`: review proposed changes with the appropriate authority.
- `vault-import`: import eligible external-vault references through the offered flow.
- `runtime-delivery`: deliver only the secret references authorized for the run/actor.
- `runtime-delivery`: deliver only the secret references authorized for the run/actor. Agent-owned instance secrets stay in the trusted server runtime and are never delivered to an agent.
## How to get to it (user POV)
@@ -30,7 +34,7 @@ Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use
### `secret-management`
Automated: [secrets service](../../server/src/__tests__/secrets-service.test.ts) and [user ownership](../../server/src/__tests__/secrets-service-user-secret-owner-scoped.test.ts) cover storage/access contracts.
Automated: [secrets service](../../server/src/__tests__/secrets-service.test.ts) and [user ownership](../../server/src/__tests__/secrets-service-user-secret-owner-scoped.test.ts) cover storage/access contracts. [Instance-secret tests](../../server/src/__tests__/agent-instance-secrets.test.ts) cover local encrypted storage, owner isolation, and exclusion from ordinary bindings.
Manual: Create a dummy secret reference, bind it through a supported field, and verify its use in a harmless run without logging the value. Update it and reload. Switch users and confirm personal values remain owner-scoped and missing credentials produce an actionable state.
@@ -49,3 +53,16 @@ Manual: Review a dummy proposal, reject one and accept another, then inspect the
- A displayed reference name is not proof that the actor can resolve its value at runtime.
- Company secrets and user-specific values have different ownership.
- Redaction needs verification in errors, activity, and run logs as well as the form.
### Storybook verification
#### `proposals`
Scope: ui
Storybook: Mount ProposalsTab pending secret/binding proposals, blocked authority, expired/resolved proposal, approval/rejection pending/error, and redacted metadata.
Production: GET /companies/{id}/secret-proposals and POST approve/reject must enforce company/admin/target authority, durable resolution and redaction; verified run-bound agent proposal creation is separate.
Sources: Source: [ProposalsTab.tsx](../../ui/src/pages/secrets/ProposalsTab.tsx), [secrets.ts](../../server/src/routes/secrets.ts), [secret-proposal-authorization.ts](../../server/src/services/secret-proposal-authorization.ts). Tests: [ProposalsTab.render.test.tsx](../../ui/src/pages/secrets/ProposalsTab.render.test.tsx), [secret-proposals-routes.test.ts](../../server/src/__tests__/secret-proposals-routes.test.ts)
### Documentation scope: Secrets and secret proposals
Company/user/proposal/vault and runtime-binding paths are mapped; every secret provider, rotation scenario, and delivery context needs separate validation.
maps/feature-map/skills.md
+42 -1
View File
@@ -1,4 +1,8 @@
# Skill discovery, authoring, and policy
---
navigation: {"section":"Agents and reusable capabilities","sectionOrder":30,"order":30}
---
# Skills and Skill Studio
Operators discover or import skills, author and test them in Skill Studio, manage source versions, and decide which agents may use them.
@@ -61,3 +65,40 @@ Manual: Enable the skill for one test agent and leave another without access. Ru
- Installed does not mean enabled for every agent.
- Read-only GitHub/bundled skills may require a writable copy rather than an in-place edit.
- Studio interaction coverage is in [questions and approvals](./questions-and-approvals.md); a passing mock is not a live harness test.
### Project repository source behavior
New GitHub project repositories import skills automatically. Skills → Sources lists
accessible legacy repositories with Import skills, shows source/project provenance,
groups matching repository/ref workspaces into one row, and shows queued/importing feedback,
and provides Refresh and Automatic updates in its source menu. Verify future additions,
retained exclusions, error recovery and reload persistence. Private-only sources must
be absent for unrelated people/agents; access through either originating project is sufficient.
Storybook/browser coverage uses scoped fixtures. Live GitHub-to-routine execution
must be verified separately; inspect resolved version IDs across an upstream update.
### Connection repair during an update
A missing tracked branch is a branch repair, not a credential failure. On an independent
source, choose a new branch from the searchable list or enter its name. The repository's
default branch is marked and included even outside the first 100 listed branches.
Loading or a failed list request does not prevent manual entry; saving validates the
requested ref. Installed identities, selections and version pins remain. Project-tracked
branches are changed in project settings. A saved connection
is validated against both the repository and tracked revision before repair succeeds.
Open Choose connection while a source is being refreshed. Select an authorized account and save. If the source changes, the dialog must retain that selection, load the current revision, and allow a second save without reopening. The [project repository browser suite](../../tests/storybook-visual/project-repository-skills.spec.ts) covers this recovery with simulated upstream data.
### Storybook verification
#### `testing`
Scope: ui
Storybook: Studio test inputs/configuration, running, question/approval, result and failed test states.
Production: Run bounded test of actual saved version with correct selected account/environment; inspect persisted test detail and eligible interaction response.
Sources: Source: [SkillStudio.tsx](../../ui/src/pages/SkillStudio.tsx), [companySkills.ts](../../ui/src/api/companySkills.ts). Tests: [SkillStudio.test.tsx](../../ui/src/pages/SkillStudio.test.tsx), [company-skill-test-runs-service.test.ts](../../server/src/__tests__/company-skill-test-runs-service.test.ts)
### Documentation scope: Skills, Skill Studio, and teams
Main library/Studio/source/policy and CLI team-install paths are mapped. Full source-provider conflicts, harness sync, and remote package variants remain; catalog UI is not a current top-level route.
maps/feature-map/status-cards.md
+35 -1
View File
@@ -1,4 +1,8 @@
# Status cards and refreshed summaries
---
navigation: {"section":"Automation and structured work","sectionOrder":60,"order":40}
---
# Status cards
The status-card experiment turns a saved prompt/query into an inspectable summary of watched work, with refresh history, configuration, and archive/restore controls.
@@ -44,3 +48,33 @@ Manual: Change a disposable card’s prompt or summarizer, run the offered rebui
- Summary quality needs comparison against source work, not just a successful task status.
- A saved old summary must not be counted as a successful new refresh.
- Experimental visibility, author permissions, and agent ownership constrain mutation.
### Storybook verification
#### `authoring`
Scope: ui
Storybook: Mount CreateStatusCardDialog and StatusCardSettingsForm prompt, summarizer, refresh options, required/invalid inputs and save errors.
Production: POST /companies/{id}/status-cards and PATCH /status-cards/{id} must enforce gate/author authority, save configuration and start expected compile task when prompt changes.
Sources: Source: [CreateStatusCardDialog.tsx](../../ui/src/pages/StatusCards/CreateStatusCardDialog.tsx), [StatusCardSettingsForm.tsx](../../ui/src/pages/StatusCards/StatusCardSettingsForm.tsx), [status-cards.ts](../../server/src/routes/status-cards.ts). Tests: [StatusCardSettingsForm.test.tsx](../../ui/src/pages/StatusCards/StatusCardSettingsForm.test.tsx), [status-cards.test.ts](../../server/src/__tests__/status-cards.test.ts)
#### `generation`
Scope: ui
Storybook: Mount card tile/drawer compiling, refreshing, failed, stale existing summary and successful new-summary states with linked task.
Production: POST /status-cards/{id}/recompile and /refresh plus update/finalization engine must persist actual new output/history; compare saved summary with source tasks, not merely successful task status.
Sources: Source: [StatusCardTile.tsx](../../ui/src/pages/StatusCards/StatusCardTile.tsx), [StatusCardDetailDrawer.tsx](../../ui/src/pages/StatusCards/StatusCardDetailDrawer.tsx), [status-cards.ts](../../server/src/routes/status-cards.ts), [status-card-update-engine.ts](../../server/src/services/status-card-update-engine.ts). Tests: [StatusCardTile.test.tsx](../../ui/src/pages/StatusCards/StatusCardTile.test.tsx), [status-cards.test.ts](../../server/src/__tests__/status-cards.test.ts), [status-card-update-engine.test.ts](../../server/src/__tests__/status-card-update-engine.test.ts)
#### `inspection`
Scope: ui
Storybook: Mount StatusCardDetailDrawer summary, watched work, update/revision history, query debug, empty/loading/error and stale summary disclosure.
Production: GET /status-cards/{id}, /updates, /summary-revisions and /dry-run must filter accessible card/source records; fixtures cannot establish summary truth or query authorization.
Sources: Source: [StatusCardDetailDrawer.tsx](../../ui/src/pages/StatusCards/StatusCardDetailDrawer.tsx), [status-cards.ts](../../server/src/routes/status-cards.ts). Tests: [StatusCardTile.test.tsx](../../ui/src/pages/StatusCards/StatusCardTile.test.tsx), [status-cards.test.ts](../../server/src/__tests__/status-cards.test.ts)
#### `archive`
Scope: ui
Storybook: Mount StatusCards and ArchivedStatusCardRow active/archived list, restore pending/failure and old-summary state. Archive differs from deletion.
Production: PATCH /status-cards/{id} archived true/false must persist and authorize change; restore may enqueue refresh, whose new outcome must be inspected rather than treating old summary as current.
Sources: Source: [index.tsx](../../ui/src/pages/StatusCards/index.tsx), [ArchivedStatusCardRow.tsx](../../ui/src/pages/StatusCards/ArchivedStatusCardRow.tsx), [status-cards.ts](../../server/src/routes/status-cards.ts). Tests: [status-cards.test.ts](../../server/src/__tests__/status-cards.test.ts), [status-card-update-engine.test.ts](../../server/src/__tests__/status-card-update-engine.test.ts)
maps/feature-map/steering.md
+20
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":60}
---
# Steering and queued messages
People can send follow-ups while an agent works, manage saved messages that have
@@ -135,3 +139,19 @@ gap; do not assume browser queue controls are available in every channel.
- An interrupted run may need verified cleanup before a saved follow-up can
start. Preserve and inspect the wait reason; see [recovery](./recovery.md).
- A healthy idle Agent Chat is waiting for input, not stranded unfinished work.
### Storybook verification
#### `drafts`
Scope: ui
Storybook: Task-keyed restored draft and attachment receipts; task switch/reload, failed send and uncertain-save recovery.
Production: Retain correct task draft across navigation and reload; inspect authoritative saved receipt before claiming delivery; do not clear storage on every harness mount.
Sources: Source: [TaskChatComposer.tsx](../../ui/src/components/task-chat/TaskChatComposer.tsx), [composer-draft.ts](../../ui/src/lib/composer-draft.ts). Tests: [TaskChatComposer.test.tsx](../../ui/src/components/task-chat/TaskChatComposer.test.tsx), [issue-queued-comments-routes.test.ts](../../server/src/__tests__/issue-queued-comments-routes.test.ts)
#### `approval-queue`
Scope: ui
Storybook: Answered question/accepted approval delivery waiting, eligible steer/interrupt, failed delivery and fresh-session-only approval.
Production: Keep response delivery durable and distinct from editable comments; coalesce once, enforce fresh-session restrictions and deduplicate concurrent/retried continuation.
Sources: Source: [TaskChatQueuedMessages.tsx](../../ui/src/components/task-chat/TaskChatQueuedMessages.tsx), [question-response-delivery.ts](../../server/src/services/question-response-delivery.ts). Tests: [TaskChatQueuedMessages.test.tsx](../../ui/src/components/task-chat/TaskChatQueuedMessages.test.tsx), [question-response-delivery.test.ts](../../server/src/__tests__/question-response-delivery.test.ts), [issue-queued-comments-routes.test.ts](../../server/src/__tests__/issue-queued-comments-routes.test.ts)
maps/feature-map/task-coordination.md
+4
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":20}
---
# Delegation, dependencies, and signoff
A larger task can coordinate child work, dependencies, reviewers, and execution controls while preserving a clear owner and a traceable completion decision.
maps/feature-map/tasks.md
+10
View File
@@ -1,3 +1,7 @@
---
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":10}
---
# Task creation and lifecycle
People create, assign, organize, discuss, and finish tasks. A task retains its owner, project, priority, history, and outputs as it moves through the work lifecycle.
@@ -49,6 +53,8 @@ Use a human/unassigned task to verify persistence without invoking a model.
Automated: [task-list helpers](../../ui/src/pages/Issues.test.tsx) cover search URLs, pagination, deduplication, and presentation constants. The suite does not render the page or exercise filtering, grouping, opening a task, and returning; those interactions still need a running-browser check.
Manual: Seed human-created, agent-created, scheduled routine, human-initiated chat-channel, and creator-less tasks. Confirm automation is hidden by default, **show agent-created tasks** reveals it, reload preserves the choice, and Clear filters hides it again. Verify list and board search with automation newer than the human results, and expand contextual ancestors/subtasks without promoting unrelated automated roots. Repeat in project task lists. Agent profiles and task-detail subtasks retain complete history.
Manual: Filter by status and assignee, change grouping/sort, open a task, and return. Verify the correct records and selected view survive navigation and reload. Include an empty result and a failed request.
### `task-detail`
@@ -71,3 +77,7 @@ Manual: Add a comment and edit authorized properties. Reload and verify history,
- A status label alone does not prove that the requested work exists.
- Single-assignee and atomic checkout rules still apply when tasks are created from different hosts.
- Use [coordination](./task-coordination.md), [steering](./steering.md), and [documents](./documents-artifacts.md) for their distinct workflows.
### Documentation scope: Tasks, conversations, and attention
Recipes cover the main task/conversation/attention workflows. Full shell, permission, attachment, long-thread, and concurrency permutations remain to be enumerated.
maps/feature-map/teams.md
+5 -1
View File
@@ -1,4 +1,8 @@
# Team packages and catalog installation
---
navigation: {"section":"Agents and reusable capabilities","sectionOrder":30,"order":40}
---
# Team packages and installation
Operators can preview and install a team package with its agents and related resources. Catalog/package installation is available through the CLI/API; the repository also contains catalog UI components that are not a current top-level route.
maps/feature-map/workspaces.md
+43 -1
View File
@@ -1,4 +1,8 @@
# Execution workspaces, services, and files
---
navigation: {"section":"Projects and execution","sectionOrder":40,"order":30}
---
# Workspaces, services, and files
A project or task can use a managed workspace with inspectable files, Git state, services, and runtime controls. Operators can follow its lifecycle through provisioning, use, and closure.
@@ -34,6 +38,25 @@ Automated: [workspace card](../../ui/src/components/IssueWorkspaceCard.test.tsx)
Manual: Run a task that writes a small file, follow the bound workspace, and inspect the file and revision. Reload and verify links still refer to the same workspace, not another checkout or a stale run.
For fresh standard-trust tasks using an implicit repository default, create a
disposable project checkout whose shared Git storage overlaps a private task
workspace. Verify that source admission creates a separate checkout from the
configured remote, with no private local branches, commits or shared Git storage.
Reusing, closing and reopening that task must retain the company/task-bound source;
a failed workspace save must clean up only its owned checkout. Explicit workspace,
parent/channel selections, literal or task-independent branch templates, low-trust
tasks, and local or credential-bearing remote
URLs must not use this fallback. A selected checkout requires recorded default
provenance. Create tasks
through the task service with an explicit checkout ID or an inherited parent
source but no typed selection; verify denial, no clone or environment acquisition,
and preservation of unpublished branch commits. Older ambiguous bindings and
source choices changed during preparation must retain the denial. The
[remote-source tests](../../server/src/services/isolated-remote-workspace-source.test.ts)
and [preparation tests](../../server/src/services/heartbeat/workspace-preparation.test.ts)
exercise the real Git isolation and lifecycle guards. They do not qualify live
remote credentials or a provider deployment.
For task workspace selection, use the authorized task workspace API to choose a
task directory, project source, or existing workspace. Verify that a change
made during a run stays pending until the next normal admission. Submit another
@@ -84,7 +107,26 @@ Manual: Provision a disposable workspace, wait for readiness, start an available
- A link or running badge does not prove the service is reachable from the user’s browser.
- Workspace IDs, runtime leases, and repository paths are not interchangeable.
- Terminal workspace cleanup wakes after committed task/workspace/PR changes and
restores cooldown deadlines at startup. Empty lanes stop scanning. Display Git
results can lag by thirty seconds. Compatible records share one advisory Git
inspection per bounded page, while each record keeps its own delivery check.
Destructive cleanup starts a separate Git scan even if an older scan is running.
The [worker tests](../../server/src/__tests__/terminal-workspace-work.test.ts)
cover quiet lanes and deadlines. The
[service tests](../../server/src/__tests__/execution-workspaces-service.test.ts)
cover real PostgreSQL signals and retained worktrees. These tests do not
qualify an external wake alarm or a live provider deployment.
- Organizational project, source project, task files, personal `AGENT_HOME`, and
provider home have separate meanings. Private source ownership remains attached
to copied files after source configuration changes or workspace closure.
- Use [recovery](./recovery.md) for divergence/export repair and [CLI operations](./cli-operations.md) for local worktree tooling.
### Storybook verification
#### `closure`
Scope: ui
Storybook: Close-readiness checks, pending changes/active runs, blocked/pending/error close, retry close and eligible reopening.
Production: Confirm owned workspace shutdown, preserved files/Git state and permitted lifecycle transition/reopening; Browser Use session closure is unrelated.
Sources: Source: [ExecutionWorkspaceDetail.tsx](../../ui/src/pages/ExecutionWorkspaceDetail.tsx), [ExecutionWorkspaceCloseDialog.tsx](../../ui/src/components/ExecutionWorkspaceCloseDialog.tsx), [execution-workspaces.ts](../../server/src/routes/execution-workspaces.ts). Tests: [execution-workspaces-routes.test.ts](../../server/src/__tests__/execution-workspaces-routes.test.ts), [execution-workspaces-service.test.ts](../../server/src/__tests__/execution-workspaces-service.test.ts), [execution-workspace-reopen.test.ts](../../server/src/__tests__/execution-workspace-reopen.test.ts)