# ShipFoundry Documentation > ShipFoundry finds stack changes worth shipping in your product. This file combines the source-controlled launch docs for agent ingestion. # ShipFoundry Docs > Set up ShipFoundry, connect your agent, and use MCP, the API, or the CLI to turn software updates into verified work. Canonical URL: https://shipfoundry.ai/docs Find software updates that affect your product, review the evidence, and pass the work to your agents or automation. Record the result in ShipFoundry so the next review starts with that history. Start with [agent setup](/docs/agent-setup) or [dashboard setup](/docs/quickstart). Then use [agent workflows](/docs/agent-workflows) to review recommendations, schedule your own check-ins and send tasks into your existing tools. ## Start here ## Working with agents ## Working with updates ## Integrations ## Account and trust ## Read from an agent Use the [Markdown index](/docs/llms.txt) to discover individual guides or [full documentation](/docs/full.md) for all pages. The [API guide](/docs/api) includes request examples; MCP clients discover tool schemas through `tools/list`. # Product overview > Find relevant software changes and bring them into your development workflow. Canonical URL: https://shipfoundry.ai/docs/product-overview ShipFoundry monitors the software your product uses, checks updates against your project and repository, and prepares work for you or your agents to review. A recommendation includes the source change, why it may affect your product, available repository evidence, and the next question or action. A brief adds investigation or implementation instructions. Outcomes record what you decided or changed. ## Put it into your workflow You can review recommendations in the dashboard, ask a connected agent to work through them, or pull them into an existing automation through the API or CLI. For example, a weekly agent run can: 1. Read active recommendations for a project. 2. Check each recommendation's evidence and previous outcome. 3. Group the work into investigate, ready for implementation, waiting, or dismiss. 4. Retrieve a brief or task packet for the items you choose. 5. Record findings and links to completed work in ShipFoundry. You configure the schedule and execution in your agent or automation platform. ShipFoundry supplies the recommendations and stores results; it does not schedule that agent run or change your code for you. ## How recommendations are produced ShipFoundry reads public release notes, changelogs and documentation updates. It compares them with your project context and watchlist, then checks the selected GitHub repository when code evidence is relevant. The evidence determines the proposed work. Some updates need research, some need a repository investigation, and others have enough detail for an implementation task. [Brief types](/docs/investigation-briefs) explain the difference. A relevant update may have no task packet yet. Your project context should describe the product, current goals, constraints and important code. The watchlist identifies the software you want to follow. Record incorrect matches and completed work so later reviews have that history. ## Set up Create an account, choose a plan, and connect one read-only GitHub repository for each project. Linear is optional. - [Set up with your agent](/docs/agent-setup) for MCP, API or CLI access. - [Use the dashboard](/docs/quickstart) for manual setup. - [Review and route work](/docs/agent-workflows) for recurring checks and handoffs. The [ShipFoundry changelog](/changelog) describes changes to ShipFoundry itself. Your project's recommendations concern the software it depends on. # Quickstart > Create a project, connect its repository and review its first recommendations. Canonical URL: https://shipfoundry.ai/docs/quickstart This guide uses the dashboard. For setup through MCP, the API or CLI, start with [Set up with your agent](/docs/agent-setup). ## Create and describe your project 1. [Create an account](/auth/signup?plan=pro) and choose a plan. 2. Create a project for the product you maintain. 3. Add its summary, goals, constraints and important repository areas. Use facts that will help distinguish useful work from distractions: | Field | What to enter | | ---------------- | ---------------------------------------------------------------------- | | Summary | What the product does and who uses it. | | Goals | Current improvements you want to make. | | Constraints | Compatibility requirements, migration limits, budget or team capacity. | | Repository areas | Specific paths or services responsible for important behavior. | | External tools | Tools the team uses that are not visible in the repository. | Your agent can inspect the repository and prepare this context. Confirm business facts it cannot infer from code. ## Connect GitHub and choose a watchlist Connect GitHub, approve read-only access, and select one repository for the project. Review the suggested watchlist and select the dependencies and services you want to follow. Include tools outside the codebase when they affect the product. Finish the setup checks and confirm activation to start the first review. Check processing status while it runs. A successful activation request does not mean recommendations are ready yet. ## Review the results Open a recommendation and read its source evidence, repository findings and [readiness state](/docs/trust-and-readiness). Open the stored brief if one exists. Generating a new brief is an explicit action and can consume your plan's allowance. You can inspect an item yourself, give its packet to an agent, or [export a brief to Linear](/docs/linear). After the work, record what happened and include supporting files, checks or a pull-request link. [Agent workflows](/docs/agent-workflows) shows how to repeat this review through your own scheduled agent runs or other automation. ## If setup or results stall - Check the project's setup and processing status for the remaining step. - Confirm GitHub access and the selected repository. - Check that the watchlist includes items covered by ShipFoundry's sources. - If recommendations are too broad, update the product context and watchlist, and record incorrect matches. An empty update list does not prove that processing failed or that nothing needs attention. Check the reported state first. # Set Up With Your Agent > Connect your coding agent, configure a real project, and manage ShipFoundry through MCP, the API, or the CLI. Canonical URL: https://shipfoundry.ai/docs/agent-setup Connect your agent, give it access to the intended project, and let it prepare setup from the repository. You approve the account permissions and provider connections. After setup, the same connection can read recommendations, retrieve tasks and record results. ## Start here 1. [Create an account and start a trial](/auth/signup?plan=pro), or sign in to your existing account. You choose the plan and complete checkout. 2. If the dashboard shows **Start Trial**, complete checkout first. Then choose **Set Up With Your Agent**. Select your client and copy the handoff from the dialog. 3. Open the product's repository in your agent and paste the handoff. It includes connection commands and this guide. 4. For API or CLI automation, create a developer key in [Agent Access](/dashboard/settings/mcp). Existing accounts can also copy an agent handoff there. 5. Approve GitHub access yourself when requested. ShipFoundry requires one selected read-only repository per project. Linear is optional. Prefer the dashboard? Follow [Quickstart](/docs/quickstart). You can switch between dashboard and agent workflows on the same project. ## Choose a connection | Connection | Best For | Setup | | -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | [MCP](/docs/mcp) | A coding agent that discovers tools and their input schemas | Add `https://shipfoundry.ai/mcp` to your client and complete OAuth. | | [Developer API](/docs/api) | Scripts, integrations, and agents using HTTP | Create a developer key in Agent Access; send it as a Bearer token to `https://shipfoundry.ai/api/v1`. | | [CLI](/docs/cli) | Terminal workflows and automation | Use the preview CLI package supplied by ShipFoundry with a developer key. Public registry installation is not available yet. | When a setup handoff specifies a server address, use that address throughout, including for links and API requests. Do not replace it with the production addresses in this guide. Use one connection for writes. You can read through another to verify the same stored result. Repeating a write through another interface without the same explicit idempotency key can create another action. ### Permissions In MCP authorization, choose **All current and future projects** if your agent will create the project. Selecting existing projects limits access to those projects. An older connection with no project access needs fresh authorization; it is not expanded automatically. To create a new project, the credential needs `project:write` and access to all current and future projects. A selected-project grant can manage existing permitted projects but cannot create another. Project limits still apply. For setup, start with `projects:read` and `project:write`. Reading recommendations needs `updates:read`; recording decisions and outcomes needs `updates:write`; requesting briefs needs `briefs:write`. Add only the permissions your workflow needs. Revoking a credential stops its future access without deleting project history. API and CLI require an explicitly authorized developer key. MCP OAuth credentials and historical MCP-only keys are not interchangeable with developer keys. Never paste a secret into a chat, repository, issue, or handoff. Use your client's secure credential configuration. ## Give this to your agent ```markdown # Set up ShipFoundry for this repository Read https://shipfoundry.ai/docs/agent-setup.md and the guide for our connection. Use the configured MCP connection or developer credential. ## Check the account 1. Verify account identity, permissions and plan limits. 2. List projects and find one for this repository before proposing a new one. 3. Use this repository as the product. Ask only when multiple products or repositories make the target unclear. ## Prepare project context 1. Inspect the repository and identify its active dependencies and key files. 2. Propose a name, description, goals and relevant watchlist. 3. Separate code evidence from assumptions. Ask about missing business facts. 4. Read existing context before proposing changes. ## Complete setup 1. Use the tool schemas or API guide to save approved project context. 2. Ask me to complete GitHub consent, then select the authorized repository. 3. Configure the approved watchlist within plan limits. 4. Check setup status and explain any remaining action. 5. Ask before activating the first review; it can consume allowance. 6. Follow processing status until complete or a stated deadline. ## Continue with recommendations - Read evidence, questions and any existing brief or packet first. - Ask before generating a new brief or exporting work. - Inspect current code before proposing implementation. - Record only completed work, with evidence, and read back the saved outcome. ## Return - Project ID and completed setup steps. - Current processing state and request IDs. - Remaining actions or errors, with the next step for each. Keep secrets out of messages and files. Preserve idempotency keys on retries. Do not purchase, deploy, merge or create external issues without my instruction. ``` This playbook is also available as [Markdown](/docs/agent-setup.md) for agents. Use the [docs index](/docs/llms.txt) to discover individual guides, or [full documentation](/docs/full.md) when broader context is needed. A separate skill installation is not required. ## Agent procedure 1. **Discover.** MCP clients initialize the connection, inspect `tools/list`, then call `get_identity` and `get_usage`. HTTP clients read `/me` and `/usage`. Verify account identity, project grants and billing readiness before writing. A successful login alone does not mean setup is ready. 2. **Find Or Create.** List projects and identify the intended product. If absent, propose creating it. Retain the returned project ID for every later action. 3. **Describe The Product.** Read setup status. Submit evidence-based product context, goals, constraints and stack through `update_project_context` or `PATCH /projects/{id}/context`. Do not overwrite good existing context merely to repeat onboarding. 4. **Connect The Repository.** Ask the owner to complete GitHub consent using the project setup page. List the repositories already authorized to the account and select the intended one. Never guess a repository ID or reuse another account's ID. 5. **Choose The Watchlist.** Read the project's suggested and selected watchlist items. Propose relevant suggestions, then add their returned recommendation IDs. For missing items, offer to submit coverage requests through `request_stack_tracking`, then report their saved status separately from active tracking. Removing tracking preserves existing history. 6. **Finish Activation.** Check setup and processing status. Explain that activation starts the first review and can consume the account's allowance. After owner approval, call `request_activation` with `confirmed: true`, or `POST /projects/{id}/activation` with the same confirmation and a stable idempotency key. Inspect the returned dispatch state, then poll project processing status with a deadline. Admission or dispatch is not a completed review. 7. **Work An Update.** Read the update, current question, trust state and stored brief. If generation is needed, obtain approval, preserve one idempotency key and poll its returned operation ID with a deadline. Read the resulting packet before changing code. 8. **Record And Verify.** Record investigation or implementation evidence. Marking a brief used is separate from adopting an update. Read the update again to confirm the stored outcome and summarize what remains uncertain. ## What needs your approval Account creation, trial checkout, credential permission approval, and GitHub or Linear consent remain human-controlled. Your agent can prepare the next step and link you to the relevant page, then continue after you finish. First-review activation and brief generation require your explicit approval before the agent starts work. ## When something blocks progress - **Grant is `none`:** this means no project access, even with `project:write`. Do not attempt creation. Start fresh authorization in the MCP client and approve **All current and future projects**. For an existing OpenCode connection, use `opencode mcp logout shipfoundry` followed by `opencode mcp auth shipfoundry`. This is a client OAuth flow, not an action on the Agent Access settings page. - **Auth command timed out:** check connection status and call `get_identity`. If authenticated with the intended account and grant, continue. Tool discovery alone does not prove authorization. - **Rejected creation:** permission and billing denials are not fixed by changing arguments or idempotency keys. Resolve the denial first. For uncertain network outcomes, keep the original key and payload and check existing projects before retrying. - **Unmatched stack technology:** offer to request coverage. After approval, call `shipfoundry.request_stack_tracking` with `projectId`, `name`, an optional `note`, `confirmed: true` and a stable `idempotencyKey`. Save the returned `requestId`. Read `manage_watchlist` with `action: "list"` to confirm its coverage status. A request does not enable monitoring or start paid work. Keep the item in project context and continue with supported items; never substitute an unrelated catalog entity. - **GitHub configured but no connections:** the server supports GitHub, but this account has not authorized an installation. Complete GitHub consent before selecting a repository. - **Empty account settings:** no custom preferences are stored. The endpoint returns its free-form metadata schema and supports reads only; there are no required preference fields to populate. Project setup uses project context, repository and watchlist operations. ### Previously connected clients If you already connected ShipFoundry, check the saved server address before adding another connection. Reuse the intended connection. On the authorization page, verify the signed-in identity, account and projects. If they are wrong, deny access, sign into the intended account in that browser, and retry. Login success does not guarantee tools are loaded in an existing agent session; reload the connection or start a new session if needed. ### Setup errors - **No projects:** verify the account and project grant before creating a project. - **403:** check scopes, current account role and project grant. Do not request broader access than needed. - **Billing or quota error:** show the limit and link the owner to [Billing](/dashboard/settings/billing). Never retry by changing account or bypassing the limit. - **No recommendations or packet:** report the actual processing/readiness state. Do not invent an update or silently start paid work. - **Uncertain write:** retain the request and operation IDs. A `reconciliation_required` response requires reconciliation, not a new idempotency key. - **Unsupported operation:** describe the missing capability and the exact dashboard step. Tool availability is not proof that the whole workflow completed. ## Next guides - [MCP Connection And Tool Workflow](/docs/mcp) - [API Requests And Retry Rules](/docs/api) - [CLI Configuration And Commands](/docs/cli) - [Working With Briefs And Outcomes](/docs/agent-workflows) - [Security And Data](/docs/security-and-data) # Agent workflows > Review recommendations, route work to your tools and record what happened. Canonical URL: https://shipfoundry.ai/docs/agent-workflows Use ShipFoundry from an interactive agent session, a scheduled check-in, or an existing automation. [MCP](/docs/mcp) gives agents discoverable tools; the [API](/docs/api) and [CLI](/docs/cli) let scripts retrieve the same project records and write outcomes. Start with [agent setup](/docs/agent-setup) if you have not connected a project. ## Run a recurring review Configure the schedule in your agent or automation platform. Give the run a project, a review scope and permission limits. For a weekly check-in, start with this prompt: ```markdown # Review this project's ShipFoundry recommendations ## Scope - Use the ShipFoundry project for the repository open in this workspace. - Confirm the project ID before reading or writing. - Review active recommendations and their previous outcomes. - This run is for triage. Do not change code or generate new briefs. ## Review 1. Read project status and list recommendations, following pagination. 2. Read the evidence and current question for each candidate. 3. Check relevant local files when needed to assess applicability. 4. Group findings into investigate, ready for implementation, waiting, and dismiss. These are report categories, not API outcome values. 5. Link each finding to its update ID and existing brief or packet. ## Return For each item, report: - Recommendation and update ID. - Why it applies, with evidence or the unresolved question. - Proposed next step and the reason for its priority. - Any approval, missing context or dependency needed to proceed. Ask before recording decisions, starting generation or exporting work. ``` For unattended runs, define the allowed writes and spending limits in advance. A read-only review can retrieve existing briefs and packets without requesting generation. Preserve pagination cursors and retry keys when your automation resumes interrupted work. ## Take one item through to an outcome 1. Read the update, evidence, current question and previous outcomes. 2. Retrieve its stored brief and task packet. If neither is ready, report the missing step. Request generation only when authorized. 3. Check whether the task calls for research, investigation or implementation. 4. Inspect the current repository before making changes. Follow the task's scope and verification steps. 5. Record the result with the files inspected or changed, test results and any PR or commit URL. 6. Read the update back to confirm the saved outcome. Use `investigated` for completed inspection; use `adopted` only when the change was implemented. Marking a brief used records that it was used, not that its recommendation was adopted. ## Record usefulness feedback Usefulness is explicit feedback, not a side effect of closing or completing work. After a completed or dismissed recommendation with no recorded feedback, normally ask one short optional question: "Was this useful? You can also tell me what missed." Skip it when feedback already exists, was declined, or the customer moves on. Closing succeeds whether or not the question is answered. Record the answer with `decide_update` (`useful` or `not_useful`) plus an optional note, through the API `POST /updates/{id}/decisions`, the CLI `updates decide`, or the dashboard feedback buttons. Feedback never reopens the item, never overwrites implementation evidence, and never affects ranking. Dismissing a recommendation is a resolution, not a usefulness rating: do not treat one as the other. To list only items waiting on the customer, filter the queue with `workspace=needs_input` (MCP, API, and CLI) or the Needs Your Input view (dashboard). ## Send work to another tool | Destination | How to hand off | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Another agent session | Copy the task packet with the project, repository and update ID. | | Your automation | Retrieve the packet through MCP or HTTP and pass it to your worker. Keep the update ID so results can return to ShipFoundry. | | Linear | Preview the issue, then explicitly export the generated brief. Reuse the stored issue link if it was already exported. | | Another tracker | Use your own integration to create the task from the packet. ShipFoundry does not provide a built-in sync for that tracker. | For API and MCP writes, reuse the same idempotency key when retrying the same action. A new key can create another action. Linear status changes do not automatically update ShipFoundry outcomes. ## Choose the work the evidence supports A **Hand To Agent** packet proposes implementation with specific constraints and checks. An **Engineering Spike** asks the agent to investigate code and decide whether a change is needed. **Research Brief**, **Workflow Brief** and **Strategy Brief** address technical unknowns, operating processes or product decisions. If there is no packet, read the missing-evidence notes. If your agent contradicts the recommendation, record the finding rather than forcing an implementation. See [briefs](/docs/investigation-briefs), [readiness states](/docs/trust-and-readiness) and the [sample investigation](/docs/sample-investigation-brief). # MCP > Connect your agent to read recommendations, manage projects and record outcomes. Canonical URL: https://shipfoundry.ai/docs/mcp Connect your agent to ShipFoundry at: ```text https://shipfoundry.ai/mcp ``` MCP exposes tools for project setup, recommendations, briefs and outcomes. Your client discovers their arguments through `tools/list`. ## Connect 1. Open [Agent Access](/dashboard/settings/mcp). 2. Choose your client and copy its setup instructions. 3. Add the Streamable HTTP endpoint and complete OAuth. 4. Approve the intended account, project access and permissions. 5. Ask the agent to call `shipfoundry.list_projects` and confirm the result. You can connect before creating a project. Follow [agent setup](/docs/agent-setup) for the remaining steps. For clients without OAuth, use a developer key from Agent Access as a bearer token. Store it in the client's secret configuration or environment, never in a prompt or repository. Access depends on the credential's scopes, current account role and project grant. ## Work with a project Use `tools/list` to read the current schema before calling a tool. These are the main operations: | Task | Tools | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Verify account and plan | `shipfoundry.get_identity`, `shipfoundry.get_usage` | | Find or create a project | `shipfoundry.list_projects`, `shipfoundry.create_project` | | Read or update setup | `shipfoundry.get_setup_status`, `shipfoundry.update_project_context`, `shipfoundry.update_project` | | Select an authorized repository | `shipfoundry.list_available_repositories`, `shipfoundry.select_repository` | | Choose the watchlist | `shipfoundry.manage_watchlist` | | Start the first review and read progress | `shipfoundry.request_activation`, `shipfoundry.get_processing_status` | | Review recommendations | `shipfoundry.list_relevant_updates`, `shipfoundry.get_update_context` | | Read stored briefs and packets | `shipfoundry.get_latest_handoff_brief`, `shipfoundry.get_handoff_brief`, `shipfoundry.get_task_packet` | | Record results | `shipfoundry.mark_brief_used`, `shipfoundry.record_update_outcome` | Activation and generation require explicit approval and can consume allowance. Reading an existing brief or packet does not start generation. Preserve the same `idempotencyKey` when retrying a supported write. After recording an investigation or implementation result, read `get_update_context` and check `workResults` for the returned outcome ID and evidence. `decisionHistory` contains customer decisions; recording work does not automatically mark a recommendation adopted or closed. The API update-detail response and CLI `updates show` expose the same work results. ## Use it in repeated agent runs Your agent can retrieve recommendations at the start of a session or in a scheduled review, inspect the repository, and return results to the same update. Configure the schedule and permitted actions in your agent platform. See [agent workflows](/docs/agent-workflows) for a copyable review prompt and handoff options. ShipFoundry's GitHub connection stays read-only. Your agent uses its own repository access and your instructions when editing code. MCP does not expose ShipFoundry's integration-provider credentials. ## Connection problems - **Authentication required:** reconnect OAuth or check that the client sends a valid bearer key. Restart the client session if it cached an old credential. - **No projects:** verify the account and project grant before creating anything. - **Forbidden:** check the required scope and current account role. - **No packet:** read the update's readiness and missing-evidence notes. Not every recommendation has an actionable packet. For HTTP scripts, use the [Developer API](/docs/api). ## Request Missing Stack Coverage If `resolve_stack_entities` returns an unmatched tool, ask whether to request coverage. With approval, call `shipfoundry.request_stack_tracking`: ```json { "projectId": "", "name": "", "note": "How this repository uses it", "confirmed": true, "idempotencyKey": "request-missing-tool-01" } ``` Keep the returned `requestId` and read `manage_watchlist` with `action: "list"` for saved requests and their coverage status. Requested items are not monitored yet. A catalog match is reported without activating it. Continue setup with supported items while coverage is pending. # Developer API > Manage projects, retrieve recommendations and record outcomes over HTTP. Canonical URL: https://shipfoundry.ai/docs/api The Developer API exposes customer operations under `/api/v1`. It shares permissions, entitlements, recommendations, artifacts, and outcome history with the dashboard, MCP, and CLI. The endpoint catalog lives at [/api/v1/openapi](/api/v1/openapi). It currently lists routes, scopes and effects; it is not yet a complete schema for generating a client. Use the request examples below and inspect returned fields. ## Authentication Create a developer key in [Agent Access](/dashboard/settings/mcp), then set the service origin explicitly. Keep the secret in your process or client credential store. ```bash export SHIPFOUNDRY_BASE_URL=https://shipfoundry.ai # Supply SHIPFOUNDRY_API_KEY through your secure environment configuration. ``` Send the key as a Bearer token: ```bash curl "$SHIPFOUNDRY_BASE_URL/api/v1/me" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" ``` Developer keys reuse the `sfp_mcp_` credential format, with explicit Developer API resource permission, scopes, and an `all`, `selected`, or `none` project grant. Historical MCP-only keys do not automatically acquire API permission. Neither generic MCP OAuth tokens nor ChatGPT OAuth tokens authenticate to `/api/v1`. Key creation, listing, rotation, and revocation use `/api/v1/keys` with a signed-in dashboard session and the required account role. A bearer key cannot manage keys. Creating a key requires an owner or admin. Open `/dashboard/settings/mcp` and use **Developer Keys**. Choose a name, project access, permissions, and an optional expiry. Copy the secret once and store it privately. The same section lists keys and lets you confirm rotation or revocation. Rotation immediately invalidates the old secret; update your clients with the replacement. The CLI accepts `SHIPFOUNDRY_MCP_TOKEN` as a legacy environment-variable name. Its value must still be a key authorized for the Developer API; the variable name does not convert an old MCP-only key. ## Set up a project Use [Set Up With Your Agent](/docs/agent-setup) for the human consent steps and activation procedure. First read `GET /me`, `GET /usage` and `GET /projects`. A project-create request requires `project:write`, an unrestricted project grant, and available plan capacity. ```bash curl "$SHIPFOUNDRY_BASE_URL/api/v1/projects" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Idempotency-Key: $CREATE_REQUEST_KEY" \ -d '{"name":"My Product","description":"The product this repository implements."}' ``` Choose a unique `CREATE_REQUEST_KEY` for this action and retain it on retry. The successful response contains the new project ID in `data.id`. Use an existing ID from the project list instead when that project already exists. Set `PROJECT_ID` to that returned ID. Read its current context before updating: ```bash curl "$SHIPFOUNDRY_BASE_URL/api/v1/projects/$PROJECT_ID/context" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" curl -X PATCH "$SHIPFOUNDRY_BASE_URL/api/v1/projects/$PROJECT_ID/context" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Idempotency-Key: $CONTEXT_REQUEST_KEY" \ -d '{"summary":"What the product does and for whom.","goals":["Improve checkout reliability"],"constraints":["Preserve existing payment behavior"],"importantRepoAreas":["src/checkout"]}' ``` Replace example facts with evidence from the actual product. Context also accepts `domain`, `repoUrl`, `runtimeModel`, `deploymentModel`, `packageManager`, `packageName`, `importantDependencies`, `externalTools`, `investigationTargets`, and `stack` entries with `name`, optional `category`, and optional `versionConstraint`. After GitHub consent, `GET /projects/{id}/repository` lists permitted repositories. Select one with `POST /projects/{id}/repository` and `{"repoId":"","priority":0}`. Read `/status` again. `GET /projects/{id}/watchlist` returns selections and suggestions. Add suggested items with `POST` to that path and `{"action":"add","recommendationIds":[""]}`. IDs are different for repositories, suggestions and selections; never substitute names or invent IDs. ### Activate and follow progress Once setup status confirms a current repository and selected watchlist, obtain the owner's approval to start the first review. This can consume the plan's allowance. ```bash curl "$SHIPFOUNDRY_BASE_URL/api/v1/projects/$PROJECT_ID/activation" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Idempotency-Key: $ACTIVATION_REQUEST_KEY" \ -d '{"confirmed":true}' curl "$SHIPFOUNDRY_BASE_URL/api/v1/projects/$PROJECT_ID/processing-status" \ -H "Authorization: Bearer $SHIPFOUNDRY_API_KEY" ``` The activation result reports whether setup was already completed, its first-review request ID and the actual dispatch state. A pending dispatch is not accepted or completed work. Poll the project's `processing-status` endpoint with a deadline and report outstanding setup actions. The first-review request ID is not a brief-operation ID; do not poll it through `/operations`. A repeated activation of completed setup does not start another review. ## Core workflow ```bash BASE="$SHIPFOUNDRY_BASE_URL/api/v1" AUTH=(-H "Authorization: Bearer $SHIPFOUNDRY_API_KEY") curl "$BASE/projects" "${AUTH[@]}" curl "$BASE/projects/$PROJECT_ID/status" "${AUTH[@]}" curl "$BASE/projects/$PROJECT_ID/updates?workspace=active&limit=20" "${AUTH[@]}" curl "$BASE/updates/$UPDATE_ID" "${AUTH[@]}" curl "$BASE/updates/$UPDATE_ID/brief" "${AUTH[@]}" ``` Reading a stored brief never generates, spends, or queues. Generation is always explicit: ```bash curl "$BASE/updates/$UPDATE_ID/brief-requests" "${AUTH[@]}" \ -H 'Content-Type: application/json' \ -d '{"confirmed":true,"mode":"if_missing_or_stale","idempotencyKey":""}' ``` An accepted request returns HTTP 202 with an operation ID. Poll `GET /operations/$OPERATION_ID` until terminal, then read the stored brief and the execution packet: ```bash curl "$BASE/operations/$OPERATION_ID" "${AUTH[@]}" curl "$BASE/updates/$UPDATE_ID/packet?mode=full" "${AUTH[@]}" ``` Record what actually happened, with evidence: ```bash curl "$BASE/updates/$UPDATE_ID/outcomes" "${AUTH[@]}" \ -H 'Content-Type: application/json' \ -d '{"outcome":"investigated","summary":"Investigated checkout compatibility; implementation remains pending.","filesInspected":["src/checkout/index.ts"],"validationNotes":["Existing checkout tests passed."],"idempotencyKey":""}' ``` ## Other customer operations Paths below are relative to `/api/v1`. Use returned UUIDs in `{id}` and send JSON for bodies. Mutations accept `X-Idempotency-Key`; preserve it across retries. Access also depends on the project's grant and the operation's scopes. | Task | Request | Body Or Parameters | | ---------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Update project | `PATCH /projects/{id}` | `name` and/or `summary` | | Archive or restore | `POST /projects/{id}/archive` | `action`: `archive` or `restore`; `confirmed`: `true` | | Remove watchlist items | `DELETE /projects/{id}/watchlist` | `selectionIds`: array of returned selection UUIDs | | Check processing | `GET /projects/{id}/processing-status` | No body. Does not start processing. | | Check connections | `GET /connections` | No body. Consent remains in the browser. | | Read an operation | `GET /operations/{id}` | No body. Use the operation ID returned by a write. | | Cancel supported work | `POST /operations/{id}/cancel` | `confirmed`: `true`. Running or completed work may not be cancellable. | | Answer a question | `POST /updates/{id}/answers` | Current `questionHash` from the update plus `answer` as a string or array of strings. Stale questions are rejected. | | Record decision | `POST /updates/{id}/decisions` | `confirmed`: `true`; `decision`: `keep_open`, `useful`, `not_useful`, `dismiss`, or `reopen`. Dismiss requires `dismissReason`; `other` also requires `reason`. `useful` and `not_useful` record explicit feedback with an optional `reason` note and never change the recommendation state. | | Mark brief used | `POST /updates/{id}/brief-uses` | `briefId`: UUID of the stored brief. This does not mark adoption. | | Preview Linear issue | `POST /linear/preview` | `matchId`: update UUID. Preview does not export. | | Export Linear issue | `POST /linear/export` | `matchId`, `confirmed`: `true`. Read the preview first; reuse an existing export instead of forcing a duplicate. | | Read account settings | `GET /settings` | No body. Billing and credential changes remain session-controlled. | Decision dismissal reasons are `already_handled`, `does_not_apply`, `no_next_step`, `not_now`, `other`, or `too_small`. Outcome values are `useful`, `ignored`, `false_positive`, `adopted`, `investigated`, `waiting`, `needs_review`, or `deferred`. Evidence may include `summary`, `reason`, `filesInspected`, `filesChanged`, `validationNotes`, `prUrl` and `commitUrl`. Only claim adoption when the implementation evidence supports it. Recommendations can impose additional readiness requirements. ## Errors and retries Failures use stable machine codes with a request ID and recovery hint: `unauthorized`, `wrong_audience`, `forbidden`, `not_found`, `validation_error`, `conflict`, `idempotency_conflict`, `billing_required`, `quota_exceeded`, `provider_unavailable`, `service_unavailable`. For a write you may retry, choose one `X-Idempotency-Key` (or `idempotencyKey`) and keep it with the request. - Same key and request: returns the original saved result. - Same key with a changed request: returns HTTP 409. - No client key: each HTTP request receives a new key, so the server cannot recognize a retry of an earlier request. When retrying across API and MCP, use the same explicit key and equivalent arguments. MCP calls without a key keep their operation-specific behavior and do not use this shared retry record. If a write returns `reconciliation_required`, its external result is uncertain. Keep the request ID and resolve that attempt before starting another. Changing the key can duplicate the action. Cancelling a local wait never cancels server work: use `POST /operations/$ID/cancel` explicitly. ## Pagination List responses carry an opaque cursor scoped to the account, project, and filters. Cursors from another listing are rejected. The queue exposes the 50 most relevant items; refine filters to page further. ## Billing and limits Reads never spend. First-review activation, brief generation, regeneration with a reason, and Linear export are explicit, allowance-checked writes. No interface bypasses trial, billing, project, or watchlist limits, and nothing purchases automatically. `GET /usage` reports plan and quotas. ## Related guides - [Agent Setup Procedure](/docs/agent-setup) - [MCP Tools](/docs/mcp) - [CLI](/docs/cli) ## Request Missing Coverage Send `POST /projects/{id}/tracking-requests` with `project:write` permission and an `X-Idempotency-Key` header: ```json { "name": "", "note": "How this repository uses it", "confirmed": true } ``` The response includes `requestId`, `coverageStatus`, `status` and `trackingActivated: false`. Reuse the same key and payload for retries. Read `GET /projects/{id}/watchlist` and its `requests` list for saved coverage requests. This records demand; it does not enable monitoring or generate work. A tool already in the catalog returns `status: "catalog_match"` for a separate tracking decision. ### Retry a failed first review After fixing a reported failure, send `POST /projects/{id}/activation` with `{"confirmed":true,"retryFailed":true}` and a new `X-Idempotency-Key`. This is a new approved attempt, not a replay of the original activation. Keep that new key for retries of the same request. Running reviews and unresolved dispatches are not restarted. Read `/projects/{id}/processing-status` for the review outcome. ## Discover MCP schemas and Markdown guides For MCP, initialize `/mcp` and call `tools/list` for the current tool names and input schemas. Inspect tool errors even when the HTTP response is 200. See the [MCP guide](/docs/mcp) for authentication and recovery. Documentation is also available as Markdown at `/docs/.md`, with a resource map at [llms.txt](/llms.txt) and the [full documentation export](/docs/full.md). # Product CLI > Install and automate the ShipFoundry developer API from the terminal. Canonical URL: https://shipfoundry.ai/docs/cli The `shipfoundry` CLI operates the Developer API from your terminal (Node 22 or newer, or Bun). ## Availability Install the public package with Node.js 22 or newer: ```bash npm install -g @shipfoundry/cli@0.1.0 shipfoundry --help ``` The command is `shipfoundry`. It works without the ShipFoundry application source tree. ## Configure Sign in to your ShipFoundry instance and open `/dashboard/settings/mcp`. Under **Developer Keys**, create a key with access to the projects and permissions your client needs. Copy the secret once and keep it private. `shipfoundry auth login` prints these setup instructions even before a base URL is configured. ```bash export SHIPFOUNDRY_BASE_URL=https://shipfoundry.ai export SHIPFOUNDRY_API_KEY="" ``` Precedence is explicit option, environment, then non-secret profile. A base URL is required; there is no default production destination. Plain HTTP is allowed only for loopback development endpoints. `shipfoundry auth login` explains the dashboard bootstrap path; the CLI never mints keys and never persists secrets. ## Set up a project Start with `shipfoundry projects list --json`. Reuse the intended project when it exists; use `shipfoundry projects create --help` for creation options. See the [API guide](/docs/api#set-up-a-project) for the context JSON fields and the [agent setup guide](/docs/agent-setup) for consent and readiness steps. ```bash shipfoundry projects context "$PROJECT_ID" --json shipfoundry projects context "$PROJECT_ID" --file context.json \ --idempotency-key "$CONTEXT_REQUEST_KEY" --yes --json shipfoundry repositories list --project "$PROJECT_ID" --json shipfoundry repositories select "$REPOSITORY_ID" --project "$PROJECT_ID" \ --idempotency-key "$REPOSITORY_REQUEST_KEY" --yes --json shipfoundry watchlist list --project "$PROJECT_ID" --json shipfoundry projects status "$PROJECT_ID" --json ``` Repository consent happens in the browser. Select an ID returned by `repositories list`. Inspect `watchlist add --help` and add relevant returned suggestions before activation. When readiness checks pass and the owner approves starting a first review: ```bash shipfoundry projects activate "$PROJECT_ID" \ --idempotency-key "$ACTIVATION_REQUEST_KEY" --yes --json shipfoundry reviews status "$PROJECT_ID" --json ``` Activation can consume the plan's allowance. Inspect the dispatch result, then poll `reviews status` with a deadline. An accepted request does not mean the review has completed. Repository disconnection is also available through `repositories disconnect`; it requires the project-repository selection ID returned by the service and explicit `--yes`. ## Run the workflow ```bash shipfoundry doctor --json shipfoundry projects list --json shipfoundry projects status "$PROJECT_ID" --json shipfoundry updates list --project "$PROJECT_ID" --workspace active --json shipfoundry updates list --project "$PROJECT_ID" --workspace needs_input --json shipfoundry updates show "$UPDATE_ID" --json shipfoundry briefs show "$UPDATE_ID" --json shipfoundry briefs request "$UPDATE_ID" \ --mode if_missing_or_stale --idempotency-key "$REQUEST_KEY" --yes --json shipfoundry operations wait "$OPERATION_ID" --timeout 120 --json shipfoundry handoff show "$UPDATE_ID" --format markdown > handoff.md shipfoundry outcomes record "$UPDATE_ID" \ --file outcome.json --idempotency-key "$OUTCOME_REQUEST_KEY" --yes --json ``` Example `outcome.json`: ```json { "outcome": "investigated", "summary": "Inspected the checkout flow and confirmed the proposed change needs further testing.", "filesInspected": ["src/app/checkout.ts"], "validationNotes": [ "Ran the checkout tests; no implementation change was made." ] } ``` ## Automation rules - `--json` emits structured data on stdout; diagnostics go to stderr. - Reads never prompt. Every write requires `--yes`; nothing hangs on a TTY prompt. - `--wait` stops at its timeout. On timeout the operation ID is reported so another process can resume with `operations show` or `operations wait`. - Preserve `--idempotency-key` across retries; a new key per retry can duplicate paid work. - Exit codes: 0 ok, 2 usage, 3 auth, 4 forbidden, 5 not found, 6 conflict, 7 quota, 8 transient, 9 wait timeout. ## Related guides - [Set Up With Your Agent](/docs/agent-setup) - [API Authentication And Retries](/docs/api) - [MCP](/docs/mcp) ## Request Missing Coverage ```sh shipfoundry stack request --project --name "" \ --note "How this repository uses it" \ --idempotency-key request-missing-tool-01 --yes --json shipfoundry watchlist list --project --json ``` Use this after `stack resolve` reports a missing item. The request does not activate tracking or start paid work. Keep the returned request ID and check `requests` in the watchlist response for coverage status. To retry a failed first review after its cause is fixed, use `shipfoundry projects activate --retry --yes` with a new `--idempotency-key`. Poll `shipfoundry reviews status ` afterward. # Investigation briefs > Read the evidence, task scope and checks before assigning work. Canonical URL: https://shipfoundry.ai/docs/investigation-briefs A brief turns a recommendation into a task. It explains the source change, why it matched your project, what the repository check found, and what to do next. ## Read a brief Look for these details before assigning work: - **Evidence:** source links and repository references supporting the recommendation. - **Open questions:** what has not been established and where to investigate it. - **Scope:** files or behavior to inspect or change, plus exclusions. - **Verification:** checks that would demonstrate the intended result. - **Outcome:** the finding or implementation evidence to record afterward. Repository references describe the code that was checked. Your agent should verify them against its current checkout. ## Brief types | Type | Task | | ----------------- | ------------------------------------------------------------------------------------ | | Hand To Agent | Implement a specific change supported by repository evidence, then run its checks. | | Engineering Spike | Investigate the code and decide whether and how to implement. | | Research Brief | Resolve a technical or external question; report evidence and remaining uncertainty. | | Workflow Brief | Compare changes to an operating process and recommend when to use them. | | Strategy Brief | Evaluate product or commercial options and their tradeoffs. | | No Packet | No useful task is ready. Read the missing context or evidence before proceeding. | New product work starts as an Engineering Spike until the product requirements and code support an implementation task. A Hand To Agent label does not grant permission to edit or deploy; your agent follows the permissions you give it. ## Retrieve or generate Open an update in the dashboard, or retrieve its stored brief through [MCP](/docs/mcp), the [API](/docs/api) or the [CLI](/docs/cli). Reading a stored brief does not generate a new one. If generation is needed, request it explicitly and follow the returned operation until it finishes. Brief generation can consume the account's allowance. A task packet contains the instructions to pass to your worker or agent. ## After the task Record the actual result, including inspected files, validation results and links to changed code when applicable. Investigation and adoption are separate outcomes. If the recommendation does not apply, record that finding and why. For a complete example, read the [sample investigation](/docs/sample-investigation-brief). For recurring reviews and integrations, see [agent workflows](/docs/agent-workflows). # Sample investigation > A fictional example of a repository investigation and its expected result. Canonical URL: https://shipfoundry.ai/docs/sample-investigation-brief This fictional example shows what an investigation task can contain. It does not describe a real release or a repository ShipFoundry has inspected. ## Recommendation A product uses an authentication SDK. A release note describes a change to sign-in redirects. The project may need an update, but the relevant code has not been checked yet. | Field | Example | | ---------------- | -------------------------------------------------------------------------------- | | Brief type | Engineering Spike | | Readiness | Needs Repo Check | | Question | Does this product depend on the redirect behavior described in the release note? | | Known context | The product uses the SDK for sign-in and has a callback route. | | Missing evidence | Installed version, callback implementation and test coverage. | | Expected result | A finding about applicability, with file references and a proposed next step. | An actual brief would include the source URL and available repository references. This example deliberately has neither. ## Agent handoff ```markdown # Investigate the sign-in redirect change ## Inputs - Read the release note linked in the ShipFoundry recommendation. - Confirm the project and repository before starting. - Use the brief's update ID when recording the result. ## Inspect 1. Check the installed SDK version in the lockfile. 2. Find the sign-in and callback code that uses the SDK. 3. Compare the current redirect handling with the documented change. 4. Inspect the relevant tests and run them if the environment permits. ## Scope - Investigate only. Do not change code or provider settings. - Do not include secrets or raw environment values in the report. - If the release note or repository is unavailable, report that blocker. ## Return - Whether the update applies, and why. - Files inspected and evidence supporting the finding. - Tests run, their results, and any checks not run. - Remaining uncertainty. - Proposed change and verification steps, if a change is needed. Stop after the investigation. Implementation requires a separate instruction. ``` ## Record the result Record `investigated` with the inspected paths and findings. If a change is needed but postponed, record `deferred` with the reason. If the match was wrong, record `false_positive` and explain the mismatch. Use `adopted` only after the change has been made and verified. Include the changed files, test results and a PR or commit URL when available. See [brief types](/docs/investigation-briefs) and [agent workflows](/docs/agent-workflows) for implementation handoffs and recurring reviews. # Trust and readiness > Understand what a recommendation establishes and what still needs checking. Canonical URL: https://shipfoundry.ai/docs/trust-and-readiness A recommendation can match your stack before anyone has confirmed that it affects your code. Its readiness state tells you what evidence exists and which work to do next. ## Readiness states | State | Meaning | Safe Action | | ---------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | Stack Candidate | The update matches a tracked stack item or product context, but repo proof is not present. | Read and triage. Do not treat as implementation-ready. | | Needs Repo Check | The update may affect code, but ShipFoundry still needs local or GitHub-backed evidence. | Ask an agent to inspect the named areas. | | Repo Checked No Proof | A repo check ran but did not find supporting evidence. | Defer, ignore, or run a narrower check if the user knows where to look. | | Repo Checked Weak | Some possible evidence exists, but it is partial or indirect. | Investigate before implementation. | | Repo Checked Plausible | Evidence suggests the update may apply to the repo. | Create a focused investigation task. | | Repo Checked Strong | Evidence directly supports the update's relevance to repo code or config. | Consider a handoff if the suggested path is specific. | | Handoff Ready | The brief has enough synthesis, evidence, constraints, and checks for an agent workflow. | Hand to agent, export to Linear, or copy the task packet. | | Non-Code Relevant | The update matters, but the action is docs, policy, vendor setup, billing, or operations. | Assign human review or update product context. | | Not Relevant | The update does not apply to this product. | Record why it does not apply. | ## Use the evidence in your review Read the cited source and repository findings. Check which commit was inspected and whether the brief names any missing proof. Strong repository evidence supports relevance; tests and review still determine whether a proposed change works. For an agent or automation, preserve the state and missing-evidence notes with the task. Send uncertain code questions for investigation. Reserve implementation tasks for recommendations with specific code references, scope and checks. If your agent finds contradictory evidence, stop the proposed implementation and record what it found. An important update can remain worth investigating even when the initial repository check found no proof. See [brief types](/docs/investigation-briefs) and [agent workflows](/docs/agent-workflows). # GitHub repository connection > Connect a repository so ShipFoundry can check recommendations against your code. Canonical URL: https://shipfoundry.ai/docs/github-repo-evidence Each project needs one connected GitHub repository. ShipFoundry reads it to check whether a software update affects your implementation and to give your agent specific files to inspect. ## Connect a repository 1. Open the project's setup page and connect GitHub. 2. In GitHub, approve access to the repositories you want ShipFoundry to read. 3. Back in ShipFoundry, select the repository for this project. 4. Check setup status before starting the first review. An agent can list and select repositories after you approve GitHub access. See [agent setup](/docs/agent-setup) for the MCP, API and CLI steps. GitHub consent stays in the browser. ## What the connection provides Recommendations can include file references and evidence tied to the repository and commit that were checked. Read these alongside the original release note or source document. A connection alone does not establish that an update applies. A check may find direct evidence, a possible connection, or no supporting code. The [readiness state](/docs/trust-and-readiness) records that distinction. Updates about operations or product decisions may still matter without a code change. When your agent takes the work, have it check the current checkout. Files may have changed since ShipFoundry reviewed them. The [brief and task packet](/docs/investigation-briefs) give it the findings, remaining questions and checks to run. ## Access This connection is read-only. ShipFoundry does not use it to edit files, create commits, open pull requests or change workflows. Repository checks collect evidence for recommendations; they do not provide a secret-scanning service or mirror every file by default. Your coding agent's permission to change code is separate from ShipFoundry's GitHub access. ## If evidence is missing or stale - Confirm that the project has the intended repository selected and GitHub access is still valid. - Check the referenced commit and files. Refresh project context when the implementation has changed. - Read the missing-evidence notes. A completed search may find no applicable code; repeating it is not necessarily useful. - If your agent finds that a recommendation is wrong, record its finding as an outcome with the inspected paths. Continue with [reviewing updates with an agent](/docs/agent-workflows) or [setting up a project](/docs/quickstart). # Linear > Export a brief to a Linear issue and keep its link with the recommendation. Canonical URL: https://shipfoundry.ai/docs/linear Export a generated brief to Linear when you want it in your team's work queue. Each export creates an issue and stores its identity in ShipFoundry. Matching an update does not create an issue automatically. ## Connect and choose a target 1. Connect Linear in [Integrations](/dashboard/settings/integrations) and approve the workspace. 2. Configure the ShipFoundry project's Linear target. 3. Select a team and, optionally, a project, cycle, labels, assignee and priority. The connection uses OAuth. ShipFoundry stores its access token encrypted on the server; your coding agent does not need that token. ## Export a brief Open a generated brief and review its evidence and task instructions. Choose **Create Linear issue**, then check the returned issue link. An agent can check the connection and preview an issue before exporting through [MCP](/docs/mcp) or the [API](/docs/api). Export requires explicit confirmation. Keep the same idempotency key on retries and reuse the stored issue link when the brief was already exported. Research, engineering, workflow, strategy and implementation briefs can become issues. An update with **No Packet** needs its missing context or evidence resolved first. ## Record the result in ShipFoundry Linear issue status does not sync back to ShipFoundry. When the work finishes, have your agent or automation record the outcome against the original update, with implementation or investigation evidence. This integration exports briefs; it does not import issues or synchronize the rest of your Linear workspace. You can use ShipFoundry without connecting Linear. ## If export fails Check that the Linear connection is active and the project has an enabled export target. If the target is wrong, correct it before exporting another brief. If an issue was already created, use its stored link rather than creating a duplicate. See [agent workflows](/docs/agent-workflows) for other ways to pass tasks to your tools. # Security and data > Understand account access, repository data, credentials and account deletion. Canonical URL: https://shipfoundry.ai/docs/security-and-data ShipFoundry stores project context, repository evidence, recommendations, briefs and outcomes so your team and agents can work from the same records. This page describes product behavior; it does not replace the legal policies. ## Account access Account and project records are private to the account. Requests are checked against account membership and role. Agent credentials also carry permissions and project grants. Public release information can be reused across accounts. Private project context and outcomes remain account-scoped. ## Stored data | Data | Purpose | | ----------------------------- | --------------------------------------------------------------- | | User and account records | Membership, preferences and access. | | Billing records | Subscription status and plan limits. | | Project context and watchlist | Product description, goals, constraints and software to follow. | | Public source information | Update summaries, source references and matching information. | | Repository evidence | Findings associated with a selected repository and update. | | Briefs and task packets | Instructions for investigation or implementation. | | Outcomes and audit events | Decisions, work results and action history. | | Integration records | Connection state and configuration for connected services. | ## Credentials and repository access Use MCP OAuth where your client supports it. For API, CLI or bearer-token MCP access, create a scoped key in [Agent Access](/dashboard/settings/mcp). Keep secrets in your client's credential store or environment. Do not paste them into prompts, issues or source files. An agent needs its ShipFoundry credential, not the provider credentials used by ShipFoundry's integrations. GitHub access is read-only and limited to the repositories you approve. Linear exports are explicit and tied to briefs. See [GitHub](/docs/github-repo-evidence) and [Linear](/docs/linear) for their connection details. Repository evidence is not a secret-scanning service. Review the context you submit and avoid including secrets or unnecessary private information in briefs and outcomes. ## Cancel or delete an account Cancel a subscription through **Billing** and the Stripe customer portal. Cancellation does not delete your account. A single-owner personal account can request deletion in **Account settings** after cancellation is completed or scheduled. Deletion removes account-owned product data and integration credentials, anonymizes retained operational records, and deletes the sign-in account after billing and data cleanup succeed. Team accounts, multiple-owner accounts, privileged accounts, and cases needing storage verification or content reassignment require support review. The product blocks self-service deletion for those cases. ## Check unexpected results If evidence points to the wrong repository, check the project's selection and connection. If a brief contains too much context, review the project profile and integration access. Revoke credentials you no longer use; revocation stops future access without deleting project history.