Files
PaperClipAI/maps/feature-map/coverage.json
T
DottaandPaperclip 7d9b93aee2 docs: establish paired feature and agent access maps (#16025)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Contributors use the feature map to understand and verify product
capabilities.
> - Agents need APIs and usable entry points within their permission
boundaries.
> - Product recipes and agent access need separate records with shared
capability IDs.
> - This pull request establishes that contract and gives maintenance
ownership of both maps.
> - The benefit is repeatable access review without changing product
behavior or permissions.

## Linked Issues or Issue Description

Refs: #15983, which added the portable verification skills and updated
the feature map. This is its contract-only follow-up. Related: #15288
added the original feature map.

**Issue type**

Missing documentation and maintenance contract.

**Where is the issue?**

The product map, its missing agent access companions, and the
verification skills.

**What's wrong?**

There is no shared convention for API presence, agent entry points,
permission boundaries, access gaps, or evidence. An API declaration does
not prove that a permitted native or remote agent can use it.

**Suggested fix**

Keep the product and agent access maps as siblings under `maps/`. Reuse
capability IDs. Record representative source inventory separately from
operation review and live proof. Keep both maps aligned through the
maintenance skill.

## What Changed

- Move the existing product map to `maps/feature-map/`. Preserve its
recipes and Poteto format. Update relative links and add companion
links.
- Add `maps/agent-access-map/` with 35 area files and 171 matching
capability IDs. Seed representative API operations, agent paths,
policies and known gaps from the reviewed source inventory. Mark entries
as `baseline`, `source-only`, and live verification `not-run`.
- Define the shared contract in `maps/README.md`. Track API presence,
agent availability, policy, evidence and review depth separately.
Require operation enumeration before marking a broad capability
operation-reviewed.
- Extend `maintain-verification-skill` to reconcile both maps and
inspect actual route policy and production tool admission. Update
creation, verification, notices and contributor references to use the
shared contract.
- Add `scripts/check-maps.mjs` and ten regression tests. Check matching
areas/IDs, indexes, references, contract fields, API method/path
examples, justified exceptions and evidence-state consistency.
- Keep the coverage inventory unchanged. Preserve skill invocation
policies and both MIT license blocks. No product API, permission, UI,
runtime helper, migration, dependency or workflow changes.

## Verification

- Passed: `node scripts/check-maps.mjs` reports 35 paired areas and 171
matching capability IDs. All local map references resolve.
- Passed: `node --test scripts/check-maps.test.mjs` runs ten tests.
Fixtures cover missing companions, renamed/orphan/duplicate IDs, broken
references, missing operation fields, empty exceptions, missing API
examples, empty policy fields, and verified evidence without passed
verification.
- Passed: metadata validation for all three verification skills. Skill
and contributor links resolve. Invocation policies and both license
blocks are unchanged.
- Compared relocated recipes with current master. Contents differ only
in relative links and companion links. `coverage.json` is byte-for-byte
unchanged. Master's updated read-only interaction test reference is
retained.
- Passed: `git diff --check`. The branch starts from current master and
contains only this contract change.
- Repository-wide typecheck, tests and build were not run locally for
this documentation and Node structural-check scope. Live agent access
was not exercised. Those gaps are explicit in the baseline entries; the
structural check does not certify behavior. CI and automated review are
pending.

## Risks

- The companions are representative source baselines. They are not
complete operation inventories or passed agent journeys.
- The checker cannot establish actual permissions, native tool
admission, operation completeness or truthful live evidence. Maintenance
must inspect source and verify with the actual permitted agent context.
- External links to the old product-map directory may need updates.
Repository references have been updated.
- Existing access gaps and board/user restrictions remain recorded. This
contract does not change authority or implement missing paths.

## Model Used

OpenAI GPT-6 through Codex assisted with this change. The session does
not expose the exact serving model ID, configured context-window size,
or reasoning setting. Capabilities used: source analysis, file edits,
shell commands, and structural regression tests.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-10-12 14:52:28 -05:00

402 lines
16 KiB
JSON

{
"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"
]
}
]
}