Get started with Ship
Connect the product workspace, then keep the evidence trail readable.
Start with a workspace, connected repos, tracker binding, policies, knowledge, and an Inbox for decisions. The first path is about founder ownership, product decisions, and evidence.
Orientation
3 pagesWhat Ship is
A workspace for AI-assisted product delivery — humans own intent, machines act inside fences, every action leaves a trail.
Vocabulary
The seven words you'll meet on every screen: workspace, connected repo, tracker, Inbox, knowledge, process, evidence.
A day in Ship
What a normal morning looks like — open the console, drain the Inbox, glance at shipped, top up knowledge.
Setup
6 pagesQuick checklist
Short setup checklist for the operator who has done this before. Cross-links into the chapters below.
The onboarding wizard
Walk the four wizard steps end-to-end: Install GitHub App → Pick repos → Workspace tracker → Confirm.
GitHub App and repo activation
Why an App and not a token; what the App can see; the two-layer model of install scope and activation.
Binding the tracker
One tracker per workspace. Linear, Jira, GitHub Issues, GitLab, Azure DevOps — credentials and trade-offs.
Members and roles
Three roles — owner, admin, member — and the last-owner protection that saves you a support ticket.
Integrations beyond the tracker
Notion, Slack, Teams, OpenTelemetry, S3 export, custom webhook — what each is for and how to wire it.
Knowledge
5 pagesWhat knowledge is for
Why short articles age better than handbooks; what belongs in knowledge and what doesn't.
Buckets
Buckets as the unit of grouping. Workspace / project / repo / user scopes. When to split, when to merge.
Importing knowledge
Sources — repo `.ship/knowledge`, website (Firecrawl), Notion, Confluence, docs repo, uploaded files.
The distiller and the review path
Nothing publishes silently — every imported note flows through routing, synthesis, and human review.
Chat as a knowledge tool
What the workspace chat is for, and how to save a clean thread as a knowledge article.
Inbox
4 pagesDecision work, not notifications
What the Inbox is, what it carries, and the rule that anything without a decision belongs elsewhere.
The five item types
Clarification, improvement, approval, failure, exception — with the canonical action for each.
Routing rules
Handles → user, group, or strategy. Configuration health: bound, used, orphaned, unbound.
Disposition
The action vocabulary: answer, accept, approve, reject, retry, acknowledge, snooze, dismiss, reassign.
Process
5 pagesThe model
Process, states, routines, specialists — the three named pieces and how they fit together.
Reading the process editor
States, transitions, routines panel, tracker mapping, flow schedule — the panels of `/process/<id>`.
Routines
The shipped catalogue, schedule shapes (cron / event / manual), standalone vs in-process routines.
Tracker mapping and specialists
Which tickets are eligible, what role the routine plays — the two questions every routine answers at runtime.
Healthy and unhealthy routines
Empty runs, hero agents, vanity throughput, drifted prompts, quiet failures — and the cures.
Operating
3 pagesThe morning loop
Workspace health → Inbox → shipped and in-progress → knowledge drift → audit. The order of moves.
The audit log
What the log records, how to filter, who can see it, when to open it.
When the system quietly does nothing
How to detect silent failures: read absence on a cadence, cross-check with the tracker, name the expectation.
Policies, secrets, evidence
3 pagesPolicies
Admin-authored standing rules injected into every agent's system prompt. Title, body, sort order, enabled.
Secrets
Workspace integration secrets, repo secrets, agent secrets, API tokens — four stores, four blast radii.
The evidence checklist
Tracker, PR, CI, comment, knowledge, audit — the five questions that test whether a trail is solid.
Local repo
4 pagesThe `.ship/` folder
What's tracked vs ignored. Agent rule files outside the folder. What never belongs in `.ship/`.
shipctl — the local workbench
Daily-use commands: doctor, verify, sync, config. The CLI is for engineers; the console is for operators.
Authoring patterns and policies
When to author. The small loop. Pattern vs knowledge vs policy. Where the deep schema reference lives.
Bundle updates
What the 'Ship template update needed' banner means. Pins for slowing rollouts. When to skip an update.
Reference
3 pagesshipctl command reference
Every shipctl command, grouped by purpose, with one-line descriptions.
Troubleshooting
Symptom → cause → fix for common console, GitHub App, tracker, knowledge, routine, and CLI issues.
Glossary
Every term in the manual, alphabetised, with a one-line definition and a chapter link.
Implementation spec
3 pagesDiscovery contract
Phase 0–4 interview an agent runs before opening its first PR. Normative.
Protocol (RFCs)
Artifacts protocol, config schema, telemetry, adapters, folder layout.
Authoring (full reference)
Schema-heavy contributor reference — folder layout, frontmatter, hashing. The friendly version is in Local repo.
Other
1 pageLooking for something else?
Not in the Docs
Some surfaces live outside this manual so founders, product owners, platform teams, and engineers can enter at the right altitude.