Skip to content

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 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:

# 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-<version>.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-<version>.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):

# 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: <displayId>] citation shape and links back to rosetta-design.com/patterns/<slug>.

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 <email>.
  • Phone numbers (E.164 + North-American formats) — replaced with <phone>.
  • Salesforce IDs (15- or 18-character) — replaced with <sfid>.
  • Token-shaped strings (Bearer ..., rsk_..., sk-..., AWS keys) — replaced with <redacted-token>.
  • URLs with embedded credentials (https://user:pass@host) — the credential component is stripped.
  • Customer-named entities — best-effort proper-noun heuristic; replaced with <entity>.

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.