# Reference — Install guide (beta cohort participants) Participant-facing install guide for the **rosetta-agent** plugin (v0.6.x). Audience: a Salesforce architect or Data 360 practitioner at one of the beta-cohort companies. The guide assumes you know Salesforce, may have used Claude Code or Cowork before, but have not seen the rosetta-agent plugin's internals. By the end you should have the plugin installed, your bearer token captured by the runtime, and a first-run query returning a pattern-cited response. For operator-side cohort management (token issuance, telemetry-receipt confirmation, activity tracking), see the companion runbook at `beta-onboarding-runbook.md`. ## 1. What this is The **rosetta-agent** plugin gives Claude Code or Cowork access to the **Rosetta Data 360 architectural reference graph** — a curated, citation-grounded body of Salesforce architectural patterns, Architectural Decision Records (ADRs), DecisionTraces, and supporting provenance, hosted at `api.rosetta-design.com` and projected to [rosetta-design.com](https://rosetta-design.com) for human reading. What you get when the plugin is active: - **ContextPattern citations.** When you ask a Salesforce-architecture question, the plugin retrieves the most-relevant ContextPatterns from the graph and surfaces them inline with stable IDs and links back to rosetta-design.com for the full canonical body. - **ADR + DecisionTrace citations.** When the question touches a ratified architectural decision, the relevant ADR is cited; when it touches an unratified open question, the DecisionTrace is cited. - **Provenance trail.** Every cited node carries a `gateStatus` and a stable identifier so you can audit what informed the answer. - **A SKILL-driven response shape** that prefers retrieval-grounded patterns over model speculation; if Rosetta has no patterns for your query, the plugin says so explicitly rather than confabulating. What you do **not** get at v0.6.x: - **No SSO.** Authentication is a static bearer token (per RCP-C-13); no OAuth, no token refresh, no per-user identity propagation. - **No public listing.** The plugin is closed-source, distributed by invitation per RCP-C-12; there is no plugin marketplace entry. - **No public release channel.** The current release line is the closed beta; GA is gated by the §11.7 conditions documented in `build-and-ga-trigger.md`. ## 2. Prerequisites Before you install, confirm you have all four of the following. ### 2.1 Runtime You need **Claude Code OR Cowork** installed. The plugin loads into either runtime via that runtime's plugin loader. Both runtimes read the same flat plugin layout (per DT-RCP-004, RATIFIED 2026-05-24); there is no separate Cowork-specific install. - **Claude Code:** install per the upstream Anthropic docs. - **Cowork:** install via the standard Cowork onboarding. ### 2.2 `rosetta-mcp-server` binary The plugin spawns a local `rosetta-mcp-server` binary that holds your bearer token and talks HTTPS to `api.rosetta-design.com` on the plugin's behalf. The binary lives in a separate repo (`rosetta-mcp-server`); install it per that repo's README. After install, the binary must be on your `$PATH` as `mcp-server` (or you must set `ROSETTA_MCP_BIN` to the binary's absolute path). For the detailed install path and env-var setup pathway, see `mcp-server-config-reference.md` §2 (first-time setup). ### 2.3 Bearer token You need a bearer token for the `agent-harness` scope. Request one out-of-band via the private cohort onboarding channel (Vernon distributes; see §6 for the support channel). Tokens follow the shape `rsk_<32+ alphanumeric>` per ADR-GO-006. Export the token in your shell startup file: ```bash # in ~/.bashrc or ~/.zshrc export ROSETTA_AGENT_TOKEN=rsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Do not commit the token to a repo. Do not paste it into chat with Claude. The binary holds it; the model never sees it. ### 2.4 Network You need HTTPS access to `https://api.rosetta-design.com` (the default value of `ROSETTA_API_BASE`). If you are on a corporate VPN that blocks general outbound HTTPS, confirm the host is reachable before proceeding (`getent hosts api.rosetta-design.com` should resolve; a TLS handshake to port 443 should complete). ## 3. Install steps ### Step 1 — fetch the latest plugin release The plugin is distributed as a `rosetta-agent-.zip` from a private GitHub release URL. Vernon shares the URL with cohort participants out-of-band per RCP-C-12 (closed-source distribution; no public marketplace listing). The release zip contains the full plugin contents (`.claude-plugin/`, `commands/`, `skills/`, `core/`, `references/`) at the zip root. ### Step 2 — install via your runtime's plugin loader **Claude Code:** unzip the release and place the contents under your Claude Code plugin directory (typically `~/.claude/plugins/rosetta-agent/` — the exact path depends on your Claude Code install). Claude Code's plugin loader picks up `.claude-plugin/plugin.json` from the plugin root. **Cowork:** upload the `rosetta-agent-.zip` via the Cowork plugin settings UI. Cowork extracts the zip and registers the plugin with the same flat layout. ### Step 3 — verify your environment variables are exported In a fresh terminal (so your shell startup file has been re-sourced): ```bash # token should be set (do NOT echo the raw token value to a log) echo "${ROSETTA_AGENT_TOKEN:+set}" # should print: set # binary should resolve on $PATH which mcp-server # should print a path ``` If `${ROSETTA_AGENT_TOKEN:+set}` prints nothing, the env var is not exported — re-check §2.3 and your shell startup file. If `which mcp-server` returns nothing, the binary is not on `$PATH` — re-check §2.2, or set `ROSETTA_MCP_BIN` to the binary's absolute path. ### Step 4 — restart your runtime Env-var changes do NOT propagate into a running runtime. You must restart so the plugin's MCP-server child process captures the new env vars at startup per `../core/mcp-token.md` §3. - **Claude Code:** exit and relaunch. - **Cowork:** relaunch the Cowork client. ## 4. First-run verification Once the runtime is back up, run a known Salesforce-architecture query and confirm the plugin returns a pattern-cited response. **Claude Code path.** Run the `/rosetta-agent:query` slash command with a known Salesforce architectural question, for example: ``` /rosetta-agent:query What patterns exist for Customer 360 implementation? ``` Expect a response that names one or more **ContextPatterns** with the `[Pattern: ]` citation shape and links back to `rosetta-design.com/patterns/`. **Cowork path.** Open a Cowork project that is tagged with the Salesforce / Rosetta scope (the tagged-project gate per RCP-C-5). In a regular chat turn, ask the same question. Cowork's auto-detection fires the plugin; you should see the same pattern-cited response. When ODF-006 lands, Cowork also renders a reference panel inline; until then, the citations are inline in the chat response. **What success looks like.** - The response includes **≥ 1 ContextPattern citation** with the `[Pattern: ...]` shape. - A **provenance footer** at the bottom of the response names the retrieval `gateStatus` and the substrate version. - **No `[ConfigurationError]` or `[UpstreamDegraded]` bracketed prefixes** appear inline (those are failure surfaces, not success). **What to do if it fails.** Cross-reference `failure-degradation-matrix.md` for the symptom → cause → fix table. The two most likely first-run issues: - **Token not propagating to the runtime.** Symptom: inline `[ConfigurationError] missing ROSETTA_AGENT_TOKEN`. Fix: restart the runtime (matrix row 1; recipe 1). - **`mcp-server` not on `$PATH`.** Symptom: inline `[ConfigurationError] mcp-server binary not found`. Fix: verify `which mcp-server` resolves, or set `ROSETTA_MCP_BIN` (matrix row 3). ## 5. Privacy / telemetry note The closed beta runs with **telemetry on by default** per RCP-C-13. This section explains exactly what gets emitted, what is redacted before events leave your machine, and what does not leave your machine at all. ### 5.1 What gets emitted The plugin emits five categories of telemetry events back to Rosetta: - **`Activation`** — when the plugin fires on a query (Cowork auto-detect or Claude Code slash command). - **`Retrieval`** — when a `/api/v1/context` call completes (success or failure); records pattern IDs hit, retrieval tier, latency. - **`KnowledgeGap`** — when retrieval returns zero patterns; paired with the user-facing "Rosetta has no patterns for this query" message per RCP-C-9 dual-coupling. - **`GovernanceWrite`** — when a DecisionTrace, ADRApplication, or QueryTrace is written via `/rosetta-agent:record`. - **`ConfigurationError`** — when an RCP-C-6 configuration failure surfaces (missing token, rejected token, binary missing, scope insufficient). For the full event taxonomy and payload shapes, see `../core/telemetry.md` §2 and §4. ### 5.2 Client-side PII redaction Before any event leaves your machine, the plugin runs **client-side PII redaction** over every string field that could contain user input. Six PII classes are covered: - **Email addresses** — replaced with ``. - **Phone numbers** (E.164 + North-American formats) — replaced with ``. - **Salesforce IDs** (15- or 18-character) — replaced with ``. - **Token-shaped strings** (`Bearer ...`, `rsk_...`, `sk-...`, AWS keys) — replaced with ``. - **URLs with embedded credentials** (`https://user:pass@host`) — the credential component is stripped. - **Customer-named entities** — best-effort proper-noun heuristic; replaced with ``. The redaction discipline is documented in `../core/telemetry.md` §6; the verification test vectors live at `pii-redaction-test-vectors.md`. ### 5.3 What does NOT leave your machine - **Your bearer token.** The `mcp-server` binary holds it in process memory and uses it for `Authorization: Bearer` headers; the model never sees the token; telemetry construction is upstream of header attachment. - **Raw query text.** Every query string passes through the redaction pipeline before it appears in a telemetry payload; the `queryHash` is computed over the redacted text. - **rosetta-app-server credentials.** The plugin has no upstream database credentials; it only holds the bearer token for the HTTPS API. ### 5.4 No opt-out during the beta The closed beta has **no telemetry opt-out mechanism**. The cohort is consenting via the deployment context (closed beta, invitation only). A per-participant opt-out toggle is a post-GA design question; the beta holds the line per RCP-C-13. ## 6. Getting help - **Support channel.** Contact your cohort manager via the private cohort onboarding channel — the same channel through which your bearer token was issued (§2.3). Any dedicated support channel will be announced there. - **Office hours.** Ad-hoc during the beta: raise issues through the support channel as they surface. Scheduled office hours will be announced if the support load warrants them. - **SLO target.** Best-effort during the closed beta; **not 24/7**. The beta is a learning cycle; production-grade SLOs come after GA per the §11.8 post-GA roadmap. - **Escalation path.** Participant → cohort manager (Vernon, acting per ODF-001) → engineering (Vernon, or the named handoff team per ODF-003 once it resolves) as needed. For symptoms that match the failure-degradation matrix, run the matching diagnostic recipe before escalating; that resolves most first-run issues without cohort-manager intervention.