Source: https://velofy.co/trove/ship/ [Trove](https://velofy.co/trove/) / Guides # Handoff docs with trove ship How trove ship turns a project and its trove into handoff docs, removes secrets and private details, tunes rules with .troveignore, and fails closed. `trove ship` turns a project and its trove into developer handoff docs: an overview, architecture, setup, conventions, decisions and gotchas. Every document is redacted before anything is written, and the run refuses to write at all if a high-confidence secret survives. ``` trove ship --dry-run # show what would be removed, write nothing trove ship # Markdown folder in .trove/ship/ trove ship --format single # one HANDOFF.md trove ship --format site --out docs/handoff ``` The same pipeline is also built as a separate binary, `trove-ship`, with the same flags. Inside Claude Code, `/trove:ship` drives it for you. ## First principles A new developer or contractor needs to know what the project is, how to build it, the rules of the house, what was decided and where the traps are. Almost all of that already exists in the repository: the engine index, the project trove, the build manifests, the continuous integration (CI) steps, the agent rule files and the architecture decision records (ADRs). So the docs are composed from those facts by fixed rules, and the same inputs always produce the same bytes. The same sources also hold things that must not leave the team: keys, email addresses, internal hosts, customer names. Some of these have a recognizable shape and some do not. That leads to layers: shape-based detectors, project rules in `.troveignore` for names only the team knows, and an optional review by a coding agent for whatever is left. Because a leak cannot be undone once a file is shared, the last step checks the exact bytes about to be written, and a surviving secret stops the run with nothing written. ## The pipeline 1. **Index.** With `--reindex auto` (the default), build `.trove/` only if no index exists. `always` refreshes it first; `never` uses whatever exists and never writes to `.trove/`. 2. **Collect** the facts listed below. 3. **Compose** six documents from them. 4. **Redact** every document: all detectors scan all documents first, then every finding is applied everywhere, so a value found in one document is removed from all of them. 5. **Review** (optional) with a coding agent, on already-redacted text. 6. **Render** the chosen format. 7. **Verify** the rendered files, then write them with a redaction report. ## What goes in * **The engine index**: subsystems, modules and their exported symbols, entry points such as `main` functions and `main.rs` or `index.ts` files, the most used imports, and recorded patches from `trove patch` (the latest 30). * **The project trove** at `.claude/trove/`, flat and sectioned entries alike. Your personal trove in `~/.claude/trove` is never shipped. * **Well-known files**: `README.md`, build manifests (`Cargo.toml`, `package.json`, `Makefile`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Dockerfile`, compose files, `justfile`), CI workflow `run:` steps (the first 20), agent rule files (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `.cursorrules`, `.windsurfrules`, `.cursor/rules/`, `.github/copilot-instructions.md`), ADRs in folders named `adr`, `adrs`, `decisions` or `decision-records`, formatter and linter configuration, and test folder layout. * **Environment variable names** from `.env.example` and similar templates. Values are never copied, and `.env` itself is never read. * **Code markers**: `TODO`, `FIXME`, `HACK` and `XXX` comments (the first 60). Skipped: `.git/`, `.trove/`, `target/`, `node_modules/`, the output folder, files over 512 kilobytes, anything Git ignores, and paths listed in `.troveignore`. Files under `fixtures`, `testdata`, `vendor` and `third_party` folders count toward the layout but are not read, because they describe someone else’s project. ## The six documents * **Overview** (`overview.md`): the README introduction, languages, file and index counts, build systems, project trove counts, the top-level layout, and trove entries of type `reference`, `project` and `snippet`. * **Architecture** (`architecture.md`): subsystems, modules, entry points and dependencies from the index. * **Setup** (`setup.md`): build and run commands, environment variable names, CI steps, and the README’s setup sections. * **Conventions** (`conventions.md`): agent rule files, trove entries of type `preference` or tagged `convention`, tooling configuration and test layout. * **Decisions** (`decisions.md`): trove entries of type `decision`, ADRs and recorded patches. * **Gotchas** (`gotchas.md`): trove entries of type `gotcha` and code markers. ## Output formats * **`folder`** (default): `README.md` linking the six documents, the six documents, `REDACTION_REPORT.md` and `redaction-report.json`, the same report as JavaScript Object Notation (JSON). * **`single`**: everything in one `HANDOFF.md`, plus the two report files. * **`site`**: a static HyperText Markup Language (HTML) site with `index.html`, one page per document, `redaction-report.html` and `redaction-report.json`. Text is escaped by the built-in Markdown renderer, and the pages follow the reader’s light or dark preference. The default output folder is `/.trove/ship/`, which the usual `.trove/` ignore rule keeps out of Git. `--out ` picks another. Ship writes a `.trove-ship` file listing the files it owns, so a re-run replaces its own files and leaves anything else alone. It refuses a non-empty folder it did not create unless you pass `--force`. ## What is removed The built-in detectors (list them with `trove ship --list-detectors`): * **Secrets**: private keys, Amazon Web Services (AWS) access keys and secret keys, GitHub, GitLab and Slack tokens, Slack webhooks, Stripe, Anthropic, OpenAI, Google, npm, PyPI and SendGrid keys, JSON Web Tokens (JWT), passwords inside web addresses, bearer tokens, secret-looking assignments and high-entropy strings. * **Personal and infrastructure details**: email addresses, phone numbers, internal hostnames, private Internet Protocol (IP) version 4 and version 6 addresses, Unix and Windows home folder paths, company names with a legal suffix, and names labelled as a customer or client. On top of those: * Your login name and home folder are treated as private. `--no-local-identity` turns that off. * The absolute repository path becomes `$REPO_ROOT`, and home folder paths become `~`. Each distinct value is replaced with a numbered placeholder such as `[REDACTED:email-1]`, `[REDACTED:host-2]` or `[REDACTED:secret-1]`, the same placeholder everywhere it appears. ## Tuning with .troveignore A `.troveignore` file at the repository root tunes what ships. Bare lines are gitignore-style paths that never enter the docs. Directives go one per line, with no trailing comments: ``` # Paths that never enter the docs secrets/ *.pem allow: oss@acme.dev allow-regex: build-\d+\.lan allow-domain: acme.dev deny: Project Nightjar deny-regex: TICKET-\d+ customer: Globex internal-domain: acme-billing.com ``` * `allow` keeps an exact value, `allow-regex` keeps values that fully match, `allow-domain` keeps emails and hosts on that domain. * `deny` and `deny-regex` always redact. * `customer` names a customer. `internal-domain` marks hosts on that domain as internal. * A high-confidence secret can never be allowed. ## Agent review The detectors only catch what has a shape. For a second pass, hand each redacted document to a coding agent: ``` trove ship --agent claude trove ship --agent-cmd "my-reviewer --json" ``` * `--agent claude` runs `claude -p --output-format text`, `--agent codex` runs `codex exec -`, and `--agent pi` runs `pi -p`. * `--agent-cmd` runs any shell command that reads the prompt on standard input and prints a JSON array of `{"text", "category", "reason"}` items. * `--agent-timeout` sets the seconds per call, 300 by default. Only already-redacted text is sent. A finding counts only if its text appears in the document, and it is redacted the same way as a detector finding. If the agent fails or times out, the whole run stops and nothing is written, because a review that did not run must not look like a clean one. ## Fail closed After rendering, the high-confidence secret detectors scan the exact bytes about to be written, and a second view with Markdown escapes and zero-width characters removed, so a key written as `sk\_live\_...` is still caught. If anything survives: ``` trove ship: refusing to write: 1 high-confidence secret(s) survived redaction conventions.md:17 (stripe-key) Fix the source (or exclude the file in .troveignore) and run again. Nothing was written. ``` The location is the output document and line, here a key that `CLAUDE.md` carried into the conventions document. The exit code is 2 and no file is written. Find the source, remove the secret and rotate it, or exclude the source file with a path line in `.troveignore`. Exit codes: `0` success, `1` any other error (for example a foreign output folder without `--force`), `2` fail closed. ## The redaction report `REDACTION_REPORT.md` (or `redaction-report.html` for a site) and `redaction-report.json` list every removed value by placeholder, category, confidence, detector, reason, length and location. The values themselves are never in the report. A summary gives counts per category, whether the agent review ran, how many files `.troveignore` excluded, and the verification result. `--dry-run` prints the report and writes nothing. `--json` prints the report as JSON in place of the text output; without `--dry-run` it still writes the docs. ## Known limits * Entries of type `convention` reach `conventions.md` only when they are also tagged `convention`. Entries of type `preference` always do, and the overview’s convention count counts only `preference` entries. Until that changes, add `--tags convention` when you write a convention with `trove remember`. * Entries of type `context`, including the generated ones, are not copied into the docs. The architecture document is built from the engine index instead. * The detectors match shapes and labels. A codename or a person’s name with no label needs a `deny:` rule or the agent review.