Read comprehension in the harness

pnyon hosts the compiled comprehension of your codebase — each module distilled to its interface, dependencies, and an LLM-written summary. This guide points a harness checkout at pnyon so get_comprehension serves those units from your Outpost's vault instead of recompiling every module locally.

The credential is a serve token: a personal access token that is identity-bound (it can read everything you can access), read-only, and revocable — think of it like a GitHub PAT. Every secret below is a placeholder; never paste a real token into a shared channel.

Quickstart (2 steps)

For a team, this is the whole setup:

1. Commit the non-secret routing to your repo's harness.config.json once — everyone shares it:

   { "comprehension": { "remote": { "enabled": true, "outpost": "<your-outpost-id>" } } }

2. Each developer runs pnyon login once. That's it — no per-repo .env.local, no env vars.

The base URL defaults to https://core.pnyon.com, and the token never lives in config (it comes from pnyon login). The sections below explain each piece and the per-developer overrides.

Before you start

• Your codebase is comprehended in pnyon (a connected Outpost whose units exist — a push has been ingested, or you've hydrated it).
• A harness build with the remote-comprehension consumer (cli ≥ 12.9, core ≥ 0.53).
• Your Outpost's id (its routing credential, shown in the dashboard).

1. Get a serve token — pnyon login

Run pnyon login. It prints a user code, opens your browser to approve, then stores an identity-bound pnyon_cst_ token in ~/.pnyon/credentials.json (mode 0600):

pnyon login                 # approve in the browser
pnyon whoami                # confirm: identity + a masked token (never the raw secret)

You authenticate once and read comprehension from every repo — no per-repo token plumbing. The harness reads the token from ~/.pnyon/credentials.json automatically, so you can leave PNYON_COMPREHENSION_SERVE_TOKEN unset (step 2). Revoke any time with pnyon logout (revokes server-side and deletes the local file). Override the pnyon-core URL with PNYON_CORE_URL.

No CLI? Mint from the dashboard instead: Serve tokens → Create token — the token (pnyon_cst_…) is shown once; copy it and export it as PNYON_COMPREHENSION_SERVE_TOKEN (step 2). Every secret below is a placeholder; never paste a real token into a shared channel.

2. Configure the routing

The non-secret routing (enable, Outpost, URL, trust) can be committed to harness.config.json so your team shares one setup. The serve token is the one exception — it never goes in config; it comes from pnyon login (or, as an override, the PNYON_COMPREHENSION_SERVE_TOKEN env var), so a secret is never committed. Any committed field can be overridden per developer or machine with the matching env var.

Committed (recommended, team-shared) — in harness.config.json:

{
  "comprehension": {
    "remote": {
      "enabled": true,                    // opt in for the repo (still gated by a token)
      "outpost": "<your-outpost-id>",     // which Outpost's comprehension to read
      // "url": "https://core.pnyon.com",    // optional — this is the default; set only to override
      "trustRemote": false                // true = serve a unit with no local source
    }
  }
}

With this committed, a teammate only needs pnyon login. CI (which has no token) stays local automatically — an incomplete config never half-enables remote.

Per-developer overrides (each wins over the committed field; set in your shell or dev-env manager, not a tracked file):

export HARNESS_COMPREHENSION_STORAGE=remote                     # force on/off
export HARNESS_COMPREHENSION_REMOTE_URL=https://core.pnyon.com     # override the base URL
export HARNESS_COMPREHENSION_OUTPOST=<your-outpost-id>          # override the Outpost
export HARNESS_COMPREHENSION_TRUST_REMOTE=1                      # override trust
# export PNYON_COMPREHENSION_SERVE_TOKEN=<serve-token>          # ONLY if you did NOT run `pnyon login`

If you ran pnyon login, leave PNYON_COMPREHENSION_SERVE_TOKEN unset — the token is read from ~/.pnyon/credentials.json. Set it explicitly only when you minted from the dashboard or run on a box that can't use the CLI (an explicit env var wins over the stored credential).

Enabled + an Outpost + a token must all resolve (from committed config, env, or pnyon login) — an incomplete configuration falls back to local rather than half-enabling remote; the URL defaults to https://core.pnyon.com.

3. How it behaves

get_comprehension becomes remote-first:

• A module you didn't check out or edit (no local source) with trust on → pnyon's unit is served directly. Query your comprehension from anywhere, no full checkout needed.
• A module whose source you have locally → the remote unit is validated against your working tree; if it matches, it's served; if your tree has diverged, the harness recompiles that one module locally.
• A cache miss or a pnyon outage → the harness recompiles locally. pnyon is never a hard dependency for a read.

Local recompiles stay local; pnyon's pipeline remains the single writer of the vault.

Discover a public Outpost

Don't own the Outpost? If you're contributing to a project that publishes its comprehension, list the public Outposts with your serve token and copy the one you want into HARNESS_COMPREHENSION_OUTPOST:

curl -s -H "Authorization: Bearer $(pnyon token)" \
  "https://core.pnyon.com/public-outposts"
# → { "outposts": [ { "outpostId": "…", "name": "Harness Engineering", "knowledgeCount": 42 }, … ] }

The directory lists only Outposts an owner has explicitly made public (id + name — never the comprehension itself), and needs a valid serve token so every caller is a known identity. knowledgeCount (shown only when above zero) flags which public Outposts actually hold comprehension. Owners flip an Outpost public from the dashboard; reads still go over your minted token and stay audited.

4. Verify

A raw check — 200 means it's working end to end:

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $(pnyon token)" \
  "https://core.pnyon.com/comprehension-unit?outpost=<your-outpost-id>&module=<a-module>"

• 200 — serving.
• 401 — the token is wrong or expired.
• 403 — the token's identity can't access that Outpost (check the Outpost id).
• 404 — no unit for that module yet (comprehend or hydrate it first).

Then run get_comprehension on a module you didn't edit — it returns pnyon's unit with no local recompile.

Security

Serve tokens are read-only (scope comprehension:read) and distinct from any control-plane credential — a leak exposes only what your identity can already read, and you can revoke it with pnyon logout or from the dashboard. pnyon login stores the token in ~/.pnyon/credentials.json at mode 0600; only pnyon token ever prints the raw value (pnyon whoami shows a masked token). Every serve is audited (identity, Outpost, module). Rotate and expire tokens as you would any personal access token.