# Install — Rosetta plugins

Welcome. This guide gets the Rosetta plugin set running on your
machine. The whole thing is two steps: **get your free API key from
your [rosetta-design.com](https://rosetta-design.com) account**
(about two minutes — §2.1 walks you through it), then **run one
install command** (§3). The install bundle ships all nine plugins
and a `MANIFEST.txt` in a single tarball. It carries no graph content:
the content lives in the production graph, which the plugins reach
through the Rosetta API.

Prefer a guided version with OS-specific tabs (macOS / Windows,
Claude Desktop and claude.ai wiring included)? Once you're signed
in, the same walkthrough lives at
[rosetta-design.com/help](https://rosetta-design.com/help).

**Producer-side contract:** `contracts/install-bundle.md`.
**Release runbook (operator-facing):** `docs/runbooks/release-cut.md`.
**Driving DTs:** the RATIFIED files under
`docs/decision-traces/install-bundle-*.md`. The
no-flag default is a **project-scoped** install per
`docs/decision-traces/install-bundle-project-scope-default.md`
(RATIFIED 2026-06-03, Option C).

## 1. What you get

Nine plugins for Claude Code or Claude.ai (`d360-distiller` and
`deploy-distiller` need Claude Code: they run in a repository checkout;
`tech-note-distiller` runs on either, but its `archive` stage needs Claude
Code):

| Plugin | Slash-command surface | Purpose |
| --- | --- | --- |
| `rosetta-research` | `/rosetta-research:*` (seven stages + `/rosetta-research:run-all`) | Canonical content pipeline. Takes an uploaded `rosetta-platform` snapshot, a target product family and a pinned evidence dataset (`--dataset`); authors `ContextPattern`, `BusinessIntent`, `VocabularyTerm`, `SemanticEntity`, `PlatformObject` and `EngineFunction` content and submits it to the Rosetta API as a content:ingest bundle, where it lands at `draft` for SME review. |
| `rosetta-archaeology` | `/rosetta-archaeology:*` (four phases) | Engagement archaeology pipeline. Takes a discovery dossier + a repo snapshot; produces an engagement-scoped Digital Twin with Context Artifacts, DecisionTraces, and a PromotionCandidate analysis. |
| `rosetta-agent` | `/rosetta-agent:*` (`query`, `turn`, `record`, `engagement`, `twin`, `govern`, `canvas`) | Live retrieval-grounded answers from the Rosetta Data-360 graph at `api.rosetta-design.com`. **Additional runtime setup required** beyond what this installer provides — see §2.5. |
| `engagement-codex` | `/engagement-codex:*` (`solution-thesis-render`, `sow-render`, `spec-manifest-render`) | Renders the engagement's documents from graph state: the Solution Thesis (four tones: `audit`, `seller`, `customer`, `leadership`), the Statement of Work, and the delivery Spec Manifest. |
| `engagement-rehearsal` | `/engagement-rehearsal:*` (`rehearse` / `eval` / `run-all`) | Persona conversation simulator for engagement gap-filling. Read-only against the graph; live mode reuses `rosetta-agent`'s MCP server, with an offline-deterministic fallback. |
| `engagement-authoring` | `/engagement-authoring:*` | Authoring-reference skills that teach an agent to correctly hand-construct the engagement-scoped payloads (engagement creation, twin documents) before writing them. |
| `d360-distiller` | `/d360-distiller:*` (`bind` / `audit` / `render` / `validate` / `run-all`) | Seed-to-skill distillation pipeline. Compiles the governed Data 360 knowledge into task-level builder skills on the Salesforce `d360_*` MCP surface. |
| `deploy-distiller` | `/deploy-distiller:*` (`project` / `publish` / `run-all`) | Graph-to-Git distillation for the Rosetta knowledge library. Projects a content snapshot of the governed knowledge into Markdown files and publishes them to the library as a pull request for its maintainers. |
| `tech-note-distiller` | `/tech-note-distiller:*` (`plan` / `draft` / `validate` / `archive` / `run-all`) | Document-to-Tech-Note distillation. Reads a practitioner document end to end, fact-checks it against official Salesforce docs, and writes Rosetta Tech Note drafts with a validator report and a hashed run bundle. Uploading a note stays a human console act. |

Plus:

- **`MANIFEST.txt`** — pinned per-plugin versions for the release
  you installed, and the line `content: none`: from `v1.0.0` the
  bundle is schema-only and carries no graph content (§4).

**Older bundles.** Bundles `v0.27.0` and earlier also carried
`db/seeds/` (Cypher seeds) and `docs/evidence/document-inventory.csv`.
Installing one still lays them down. A later `v1.0.0`-or-newer install
leaves them in place with a warning, since nothing refreshes them any
more; delete them if nothing of yours reads them.

## 2. Prerequisites

### 2.1 Your Rosetta API key (required)

The install bundle ships behind authentication, and your key comes
from your own rosetta-design.com account. Here's the whole journey:

1. **Create your account.** Go to
   [rosetta-design.com](https://rosetta-design.com) and click
   **Sign in** → **Register**. Complete the enrollment (you'll
   verify your email address), then sign in.
2. **Generate your key.** Open **Settings**, find the **API Keys**
   card, and click **Generate New Key**. Give it a name you'll
   recognize later (e.g. *laptop install*) and click **Generate**.
3. **Copy it immediately.** The full `rsk_…` key is shown
   **once** — use **Copy** or **Download JSON** before closing the
   dialog. If you miss it, no harm done: just generate another.

Then export it in your shell startup file:

```bash
# in ~/.bashrc or ~/.zshrc
export ROSETTA_API_KEY=rsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Do not commit the key. Do not paste it into chat with Claude. The
install script reads it from your environment; the model never
sees it.

### 2.2 Runtime

You need **Claude Code OR Cowork** installed. The plugins load
into either runtime via that runtime's plugin loader; both
runtimes read the same flat plugin layout.

- **Claude Code:** install per the upstream Anthropic docs.
- **Cowork:** install via the standard Cowork onboarding.

### 2.3 Graph content

The bundle carries no graph content. The plugins that read content
get it from the production graph through the Rosetta API
(`rosetta-agent`'s MCP tools, §2.5); the others work on what you
upload to them. You need no local Neo4j to use the plugins.

### 2.4 (Optional) Cowork Drive integration for the evidence corpus

The plugins reference source documents in their authoring outputs
(`evidenceSources` fields on every canonical node). The documents
themselves are in the operator's Drive; Cowork's Drive integration
authenticates plugin sessions to fetch them.

If you're running Claude Code (not Cowork), the `evidenceSources`
references work as **provenance** but you can't dereference them
to the underlying documents. This is intentional and matches the
producer-only contract — the plugins are usable without Drive
access; the documents are upstream input.

### 2.5 rosetta-agent runtime setup (if you'll use rosetta-agent)

The `rosetta-agent` plugin shipped in the bundle is not
self-contained. It spawns a local `rosetta-mcp-server` binary
that holds a bearer token and talks HTTPS to `api.rosetta-design.com`.
None of these are installed by this bundle. If you intend to use
`/rosetta-agent:query` or `/rosetta-agent:record`, follow
`util/plugins/rosetta-agent/references/install-guide.md`
§2.2–§2.3 for:

- Installing the `rosetta-mcp-server` binary from
  `github.com/vernonkeenan/rosetta-mcp-server`.
- Obtaining a bearer token under the `agent-harness` scope
  (distinct from your `plugin-install` scope; same KMS issuer).
- Exporting `ROSETTA_AGENT_TOKEN` in your shell.

If you don't intend to use rosetta-agent, the plugin files
install harmlessly and the slash commands fail closed with
`[ConfigurationError]` until the runtime prereqs land.

### 2.6 Network

Outbound HTTPS to:

- **`rosetta-design.com`** — to fetch the install tarball + script.
- **`api.rosetta-design.com`** — (rosetta-agent only) the upstream
  graph API.

If you're behind a corporate proxy, confirm both hostnames are
reachable before proceeding.

## 3. Install

Two install shapes are supported. Both pull from rosetta-design.com
behind KMS auth (Shape A reads its script from a local checkout;
Shape B fetches it from the route). Pick whichever fits your
context.

### 3.0 Scope — where the install lands

The no-flag default is a **project-scoped** install into the current
directory's `./.claude/` tree (per
`docs/decision-traces/install-bundle-project-scope-default.md`).
Two scopes are available:

| Scope | How to select | Plugins land at | Data lands at | `settings.json` merged |
| --- | --- | --- | --- | --- |
| **project** (default) | nothing, or `--project` / `SCOPE=project` | `./.claude/plugins/` | `./.claude/rosetta/` | `./.claude/settings.json` |
| **user** (machine-wide) | `--user` (alias `--global`) / `SCOPE=user` | `~/.claude/plugins/` | `~/.claude/rosetta/` | `~/.claude/settings.json` |

The installer **merges** the rosetta marketplace and enables the nine
plugins in the scope's `settings.json` so the plugins load on the next
runtime restart — no manual `/plugin marketplace add` + enable step.
The merge is non-destructive (every other key in the file is preserved)
and idempotent (re-running is a no-op). See §4 for the resulting tree
and §6 for re-run behavior.

**The wizard.** On an interactive first-touch run (a readable
`/dev/tty` and no `--yes`), the installer prints a short orientation —
it is installing into **this** project at `./.claude/`, and you can
pass `--user` for a machine-wide install at `~/.claude/` instead — then
runs a brief wizard (confirm scope, offer to skip the data payload,
which is `MANIFEST.txt`).
Because the wizard reads from `/dev/tty` rather than stdin, it works
under `curl … | bash` (where stdin is the script source). A
non-interactive run (no readable `/dev/tty`, or `--yes`) skips the
wizard and uses **project** scope silently unless you passed
`--user`/`--global`.

**Override anything.** `--target`, `--data-target`, and `--settings`
each override the scope-derived default independently; an explicit flag
always wins over the scope default.

### 3.1 Shape A — `make install-plugins` (cloned-repo users)

If you've cloned `rosetta-platform` for any reason, run (from the
project directory you want the install to land in):

```bash
make install-plugins VERSION=v1.0.0
```

Make reads `$ROSETTA_API_KEY` from your environment and threads it
through to the install script. With no `SCOPE`, this is a
**project-scoped** install into `./.claude/`:

- `TARGET=./.claude/plugins/` (plugin extraction parent)
- `DATA_TARGET=./.claude/rosetta/` (`MANIFEST.txt` parent)
- `SETTINGS=./.claude/settings.json` (merged in place)

For a **machine-wide** install, pass `SCOPE=user` (the knob threads
through to the installer as `--user`):

```bash
make install-plugins VERSION=v1.0.0 SCOPE=user
   # → ~/.claude/plugins/, ~/.claude/rosetta/, ~/.claude/settings.json
```

`SCOPE=project` (the default) and `SCOPE=global` (alias for `user`) are
also accepted.

Override individual paths independently. Extra installer flags pass
through via `INSTALL_PLUGINS_FLAGS` (Make consumes positional arguments
itself, so flags need that envelope):

```bash
make install-plugins VERSION=v1.0.0 TARGET=/somewhere/plugins/
make install-plugins VERSION=v1.0.0 DATA_TARGET=/somewhere/data/
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-data"        # plugins only
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-plugins"     # data only
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-register"    # copy files only; skip settings.json merge
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--settings /path/to/settings.json"  # explicit settings path
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--yes"            # non-interactive (project scope, no wizard)
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--dry-run"        # preview only
```

For the latest release (alias for whatever was most recently
published), omit `VERSION`:

```bash
make install-plugins   # → /install/latest/install.tar.gz
```

### 3.2 Shape B — `curl … | bash` (no clone required)

Fetch the tag-pinned install script directly from the
KMS-protected route. Run it from the project directory you want the
install to land in — the no-flag default is **project scope**
(`./.claude/`), and the wizard reads from `/dev/tty` so it still
prompts under the pipe:

```bash
# Pinned to a specific tag — project-scoped into ./.claude/
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  https://rosetta-design.com/install/v1.0.0/install-plugins.sh \
  | bash -s -- --version v1.0.0
```

For a machine-wide install, add `--user`:

```bash
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  https://rosetta-design.com/install/v1.0.0/install-plugins.sh \
  | bash -s -- --version v1.0.0 --user
```

For the latest release:

```bash
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  https://rosetta-design.com/install/latest/install-plugins.sh \
  | bash
```

Same scopes, defaults, and flags as Shape A (`--project` / `--user` /
`--global`, `--target`, `--data-target`, `--settings`, `--no-register`,
`--no-data`, `--no-plugins`, `--yes`/`--force`, `--dry-run`,
`--verbose`). The script served from
`/install/<tag>/install-plugins.sh` is byte-identical to
`scripts/release/install-plugins.sh` at the tagged tree (CI
asserts the SHA match) — fetch it, audit it before piping if you
prefer:

```bash
# audit-before-pipe variant
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  https://rosetta-design.com/install/v1.0.0/install-plugins.sh -o install.sh
less install.sh                # read it
bash install.sh --version v1.0.0
```

Both shapes verify the install tarball's SHA-256 sidecar before
extracting; neither will silently install a tampered payload.

### 3.3 Docker production builds

Pin a tag explicitly — never `/install/latest/` — in any
production Dockerfile, or your image rebuilds are not reproducible
across time:

```dockerfile
# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=rosetta_api_key \
    curl -fsSL -H "Authorization: Bearer $(cat /run/secrets/rosetta_api_key)" \
    https://rosetta-design.com/install/v1.0.0/install.tar.gz \
    | tar -xz -C /opt/rosetta/
```

The rosetta-design.com routes set `Cache-Control: immutable` on
`/install/<tag>/*` and `Cache-Control: no-cache` on
`/install/latest/*` so the immutability contract is enforced at
the HTTP layer too.

## 4. What lands where

After a successful **default (project-scoped)** install, run from your
project root:

```
<project-root>/.claude/
├── settings.json               (created or merged: rosetta-plugins
│                                 marketplace + enabledPlugins for the
│                                 nine plugins; all other keys preserved)
├── plugins/
│   ├── .claude-plugin/
│   │   └── marketplace.json     (all nine plugin entries; name 'rosetta-plugins')
│   ├── rosetta-research/        (full plugin tree)
│   ├── rosetta-archaeology/     (full plugin tree)
│   ├── rosetta-agent/           (full plugin tree; runtime setup per §2.5)
│   ├── engagement-codex/        (full plugin tree)
│   ├── engagement-rehearsal/    (full plugin tree)
│   ├── engagement-authoring/    (full plugin tree)
│   ├── d360-distiller/          (full plugin tree)
│   ├── deploy-distiller/        (full plugin tree)
│   └── tech-note-distiller/     (full plugin tree)
└── rosetta/
    └── MANIFEST.txt             (per-plugin version pins; content: none)
```

With `--user` (Make: `SCOPE=user`) the same tree lands under your home
directory instead, machine-wide:

```
~/.claude/
├── settings.json               (created or merged, as above)
├── plugins/
│   └── …                        (same nine-plugin layout)
└── rosetta/
    └── MANIFEST.txt
```

**`settings.json` is created or merged, not just copied.** The
installer writes the `rosetta-plugins` marketplace into
`.extraKnownMarketplaces` and sets `.enabledPlugins["<plugin>@rosetta-plugins"] = true`
for each of the nine plugins, so the runtime loads them on the next
restart with no manual `/plugin marketplace add` step. Every other key
in your `settings.json` is left untouched. In the pure project default
(no explicit `--target`/`--settings`) the marketplace path is written
relative (`./.claude/plugins`); otherwise it is written as the absolute
realpath of the resolved plugin target. If you passed `--no-register`
(or `--no-plugins`), the merge is skipped and you wire up the
marketplace manually (see §8). If `jq` is not installed, the installer
warns, skips the merge, and prints the exact JSON snippet to paste into
your `settings.json` by hand.

`MANIFEST.txt` records the per-plugin versions pinned by this
release:

```
platform-tag:      v1.0.0
generated-at:      2026-10-12T12:34:56Z
plugins:
  d360-distiller: 0.1.2
  engagement-authoring: 0.2.1
  engagement-codex: 0.12.0
  engagement-rehearsal: 0.1.3
  rosetta-agent: 0.6.6
  rosetta-archaeology: 0.12.0
  rosetta-research: 0.18.1
content:           none
content-snapshot:  taken after this release's prod-migrate (release-cut.md §5.1)
```

`content: none` marks a schema-only bundle (`v1.0.0` and later). A
`v0.27.0`-or-earlier bundle's `MANIFEST.txt` has `seed-corpus-sha` and
`evidence-csv-rows` lines instead, and its install also lays down
`rosetta/db/seeds/` and `rosetta/docs/evidence/document-inventory.csv`.

If you need to confirm what you installed (e.g., for a bug
report), `cat ./.claude/rosetta/MANIFEST.txt` (project scope) or
`cat ~/.claude/rosetta/MANIFEST.txt` (`--user` scope) is the answer.

## 5. First-run verification

Restart your runtime (Claude Code: exit + relaunch; Cowork:
relaunch the client) so the plugin loader picks up the new
plugin directories. For a project-scoped install, relaunch Claude
Code **in the project directory** you installed into — the merged
`./.claude/settings.json` is what registers the `rosetta-plugins`
marketplace and enables the nine plugins, so no manual
`/plugin marketplace add` step is needed.

Each plugin has a simple verification path:

**`rosetta-research`:**

```
/rosetta-research:product-family-research
```

The command's intake skill prompts you for a `rosetta-platform`
snapshot zip and a target product family. If the command is
listed in your runtime's slash-command palette, the plugin is
loaded.

**`rosetta-archaeology`:**

```
/rosetta-archaeology:survey
```

Same shape — prompts for a repo snapshot and discovery dossier.

**`engagement-codex`:**

```
/engagement-codex:solution-thesis-render
```

Prompts for engagement context + tone. The four supported tones
are `audit`, `seller`, `customer`, `leadership`.

**`rosetta-agent`:**

```
/rosetta-agent:query What patterns exist for Customer 360?
```

Expect a response that names one or more **ContextPatterns** with
the `[Pattern: <displayId>]` citation shape. **If you see
`[ConfigurationError] missing ROSETTA_AGENT_TOKEN` or `mcp-server
binary not found`, the runtime prereqs in §2.5 aren't done yet** —
the plugin file install is fine; finish §2.5 and re-test.

**`engagement-rehearsal`:**

```
/engagement-rehearsal:rehearse
```

Prompts for an engagement key, then role-plays the six personas to
propose gap closures. Read-only against the graph — it proposes, you
apply. Live mode reuses `rosetta-agent`'s MCP server (§2.5); without it
the plugin degrades to an offline-deterministic run behind a loud
degradation banner, so it still loads on the install bundle alone.

**`engagement-authoring`:**

```
/engagement-authoring:engagement-creation
```

Loads the authoring-reference skill for hand-constructing
engagement-creation payloads. Its sibling is
`/engagement-authoring:twin-authoring`.

**`d360-distiller`:**

```
/d360-distiller:run-all
```

Prompts for the distillation inputs (the `bind` / `audit` /
`render` / `validate` stages are also individually addressable).

**`tech-note-distiller`:**

```
/tech-note-distiller:run-all --source=<your document>
```

Distills one document into Tech Note drafts under
`outputs/plugins/tech-note-distiller/<run-id>/` (the `plan` / `draft` /
`validate` / `archive` stages are also individually addressable). It
needs `python3` and, for its required fact-check, the Trailhead MCP
server and web search.

**What success looks like.** Each command appears in your
runtime's slash-command palette / `/help`. Invoking it triggers
the plugin's intake skill; you don't have to complete an
end-to-end run to confirm the install — the command being present is
the install-success signal.

**What failure looks like.** The slash commands don't appear in
`/help`. See §8 (troubleshooting) below.

## 6. Updating

For a specific release (substitute the tag you want):

```bash
make install-plugins VERSION=v1.0.0
```

For whatever is current right now:

```bash
make install-plugins                # → /install/latest/
```

The installer overwrites the existing plugin directories and data
files in place by default, printing a warning that names the affected
entries (pass `--yes`/`--force` to suppress that warning in scripted
runs). There is no prompt and no flag required to refresh an existing
install (see
`docs/decision-traces/install-bundle-default-overwrite.md`).
Re-run in the same scope you installed into (project by default, or
`SCOPE=user` / `--user` for a machine-wide install) so the update lands
where the existing install lives.

The `settings.json` merge is **idempotent**: re-running updates the
`rosetta-plugins` marketplace entry and the nine `enabledPlugins` keys
in place and leaves every other key untouched, so a second run produces
a byte-identical file. Re-running an update is always safe.

If you've hand-edited any installed plugin or data **file**, back it up
first — the installer is a copy mechanism for files (not a merge tool).
The copy-not-merge rule applies to the plugin trees and `MANIFEST.txt`;
only `settings.json` is merged.

## 7. Uninstalling

The installer doesn't ship an `uninstall` target; the install
layout is plain directories that you remove with standard tools.
Substitute the scope root you installed into — `./.claude` for a
project install (the default), `~/.claude` for a `--user` install:

```bash
# project scope (default) — run from the project root:
rm -rf ./.claude/plugins/rosetta-research
rm -rf ./.claude/plugins/rosetta-archaeology
rm -rf ./.claude/plugins/rosetta-agent
rm -rf ./.claude/plugins/engagement-codex
rm -rf ./.claude/plugins/engagement-rehearsal
rm -rf ./.claude/plugins/engagement-authoring
rm -rf ./.claude/plugins/d360-distiller
rm -rf ./.claude/plugins/deploy-distiller
rm -rf ./.claude/plugins/tech-note-distiller
rm -rf ./.claude/plugins/.claude-plugin
rm -rf ./.claude/rosetta
```

The installer also merged the `rosetta-plugins` marketplace and the
nine `enabledPlugins` keys into that scope's `settings.json`. The
plugin files being gone is enough to stop the slash commands from
loading, but to fully clean up, edit `./.claude/settings.json` (or
`~/.claude/settings.json` for `--user`) and remove the
`rosetta-plugins` entry from `.extraKnownMarketplaces` and the nine
`"<plugin>@rosetta-plugins"` keys from `.enabledPlugins`. Leave every
other key in place.

Restart your runtime to clear the slash-command palette.

## 8. Troubleshooting

**HTTP 401 Unauthorized from the install route.**

Either `ROSETTA_API_KEY` isn't set in the shell that ran the
installer, or the key has been revoked. Confirm:

```bash
echo "${ROSETTA_API_KEY:+set}"   # should print: set
```

If empty, re-export per §2.1 and re-run in the same shell. If
set but still 401, request a new key from the cohort channel —
yours may have been revoked or rotated.

**HTTP 403 Forbidden from the install route.**

Your key is valid but lacks the `plugin-install` scope. Cohort
participants get this scope by default; if you only have an
`agent-harness` key (rosetta-agent runtime scope), you can't use
it to fetch the install bundle. Request a `plugin-install`-scoped
key.

**The slash commands don't appear in `/help` after restart.**

Confirm the plugin directories exist at the scope you installed into
(`./.claude/plugins/` for a project install — the default; or
`~/.claude/plugins/` for a `--user` install):

```bash
ls ./.claude/plugins/
   # expect: rosetta-research/  rosetta-archaeology/  engagement-codex/  rosetta-agent/  engagement-rehearsal/  engagement-authoring/  d360-distiller/  deploy-distiller/  tech-note-distiller/  .claude-plugin/
```

If they're missing, the install failed silently — re-run with
verbose output: `make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--verbose"`
(Shape A) or add `--verbose` to the curl-piped script's
trailing arguments after `--`.

If they're present but the commands don't appear, confirm each
plugin's `.claude-plugin/plugin.json` exists at its root:

```bash
cat ./.claude/plugins/rosetta-research/.claude-plugin/plugin.json
```

If the JSON is malformed or missing, the tarball extracted
partially. Re-install.

For a project-scoped install, also confirm you relaunched Claude Code
**in the project directory** — project-scope plugins load from
`./.claude/settings.json`, which only applies when the runtime is
started in that directory.

**The slash commands still don't appear (files present, restarted
in the right directory).**

This is almost always the `settings.json` registration step. Confirm
the scope's `settings.json` carries both the `rosetta-plugins`
marketplace and the nine `enabledPlugins` keys:

```bash
cat ./.claude/settings.json   # or ~/.claude/settings.json for --user
   # expect, alongside your other keys:
   #   .extraKnownMarketplaces."rosetta-plugins" = { "source": { "source": "directory", "path": "./.claude/plugins" } }
   #   .enabledPlugins."rosetta-research@rosetta-plugins"     = true
   #   .enabledPlugins."rosetta-archaeology@rosetta-plugins"  = true
   #   .enabledPlugins."engagement-codex@rosetta-plugins"     = true
   #   .enabledPlugins."rosetta-agent@rosetta-plugins"        = true
   #   .enabledPlugins."engagement-rehearsal@rosetta-plugins"  = true
   #   .enabledPlugins."engagement-authoring@rosetta-plugins"  = true
   #   .enabledPlugins."d360-distiller@rosetta-plugins"       = true
   #   .enabledPlugins."deploy-distiller@rosetta-plugins"     = true
   #   .enabledPlugins."tech-note-distiller@rosetta-plugins"  = true
```

If those keys are absent, the merge was skipped. The two reasons:

- **`jq` was not installed** when you ran the installer. The installer
  warns, skips the merge, and **prints the exact JSON snippet** to add
  by hand — re-run and copy that snippet into your `settings.json`, or
  install `jq` and re-run (the merge is idempotent and safe to repeat).
- **You passed `--no-register`** (or `--no-plugins`), which copies the
  files but intentionally skips the merge. Re-run without those flags,
  or add the keys above by hand.

The marketplace `path` is relative (`./.claude/plugins`) for a pure
project default and absolute otherwise — either form loads, as long as
a relative path resolves against the project root you launch Claude
Code in. The marketplace name (`rosetta-plugins`) and the plugin names
in the `enabledPlugins` keys come straight from
`./.claude/plugins/.claude-plugin/marketplace.json` (`.name` and
`.plugins[].name`); if you hand-author the snippet, match that file.

**SHA-256 mismatch during install.**

The installer aborts before extracting if the tarball's hash
doesn't match the published `.sha256` sidecar. This means either
(a) the download was truncated — re-run; or (b) the release was
re-cut and the hash legitimately changed. Compare your local
`<tarball>.sha256` against
`https://rosetta-design.com/install/<TAG>/install.tar.gz.sha256`
(with your `Authorization: Bearer` header) to disambiguate.

**The installer exits 4: "tarball missing db/seeds/ payload".**

Your installer is from `v0.25.0` or earlier and the bundle is
schema-only (`v1.0.0` or later), which that installer does not
recognise. Update the installer first: `git pull` your
`rosetta-platform` clone, or use the installer served beside the
bundle (`https://rosetta-design.com/install/<TAG>/install-plugins.sh`,
§3.2), which always matches its own bundle.

**The installer refuses to run, citing a "producer working tree".**

You ran the installer from inside a `rosetta-platform` clone. With
the project-scope default the installer fingerprints the **project
root** (the nearest existing ancestor of the target — typically
`$(pwd)`), not the not-yet-created `./.claude/plugins/`, so it
refuses even on a fresh in-repo run rather than clobbering the
producer's own tree. The fingerprint is
`docs/rosetta-platform.spec-manifest.md` + `contracts/app-server-intake.md`
+ `util/plugins/` + `db/schema/` or `db/seeds/` at the git toplevel, and
it is checked before anything is downloaded. Run the
installer from a different directory — a fresh project folder for a
project-scoped install, or pass `--user` for a machine-wide install
into `~/.claude/`.

**Cowork can't find the plugins after I upload the bundle.**

Cowork doesn't consume the install tarball directly — for
Cowork, upload each plugin's `<plugin>-<version>.zip` via the
Cowork plugin settings UI individually. The install tarball is
the Claude Code consumption surface; Cowork's per-plugin
upload flow remains the Cowork-specific install path.

The per-plugin zips ship inside the install tarball at
`<scope>/.claude/plugins/<name>/<name>-<version>.zip` (project scope:
`./.claude/plugins/…`; `--user`: `~/.claude/plugins/…`) — use those.

**I want the plugins but not the data payload.**

Re-run with `--no-data` (passed through `INSTALL_PLUGINS_FLAGS`):

```bash
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-data"
```

The `rosetta/` data tree (`./.claude/rosetta/` for project scope,
`~/.claude/rosetta/` for `--user`) won't be created. The wizard also
offers to skip the data on an interactive run.

**I want the data payload but not the plugins.**

```bash
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-plugins"
```

The `plugins/` tree is left alone; only the `rosetta/` data tree is
populated. Note that `--no-plugins` also skips the `settings.json`
merge — there are no plugins to register.

**I want to copy the files but manage `settings.json` myself.**

Re-run with `--no-register`:

```bash
make install-plugins VERSION=v1.0.0 INSTALL_PLUGINS_FLAGS="--no-register"
```

The plugin trees and data land as usual, but the installer writes
nothing to `settings.json` (the legacy copy-only behavior). You then
add the `rosetta-plugins` marketplace + `enabledPlugins` keys yourself
(see the "slash commands still don't appear" entry above for the exact
shape).

**My install is at v0.1.0 and I want to know what changed in
v1.0.0 before I upgrade.**

The platform's release notes on GitHub
(`https://github.com/vernonkeenan/rosetta-platform/releases/tag/v1.0.0`)
summarize per-tag changes. For per-plugin granular changes,
each plugin's CHANGES.md inside its own directory carries that
narrative.

## 9. Getting help

- **The guided walkthrough.** Signed-in users get the full
  OS-tabbed version of this guide — including Claude Desktop,
  Cowork, and claude.ai connector wiring — at
  [rosetta-design.com/help](https://rosetta-design.com/help).
- **Issue reports.** Open at
  `https://github.com/vernonkeenan/rosetta-platform/issues` with
  the contents of your `MANIFEST.txt` attached
  (`./.claude/rosetta/MANIFEST.txt` for a project install,
  `~/.claude/rosetta/MANIFEST.txt` for `--user`).
- **SLO target.** Best-effort during pre-GA. Production-grade
  support comes after platform v1.0.0.