# Consulting the atlas from any harness

Portable counterpart to the `agentic-atlas` plugin, for harnesses that have
no plugin system: the same consultation contract, written to be copied into a
system prompt, an agent definition, or a tool-use preamble. The plugin's
`skills/consulting-patterns/SKILL.md` and `agents/pattern-librarian.md` are
the Claude Code shape of what follows; nothing below assumes a plugin, a
subagent, an installed package, a downloaded artifact, a pinned release, or a
local cache.

## Register the endpoint

Stateless Streamable HTTP, one URL, no auth:

    https://agentic-atlas.dev/mcp/

Any MCP client that speaks Streamable HTTP can register it. There is nothing
to install and nothing to keep in sync — the endpoint serves the one active
Corpus Release, and a promotion replaces it wholesale.

## The eight tools

This is the entire supported surface. A name not in this table does not
exist; there are no aliases.

| Tool | Addresses | Bounds |
|---|---|---|
| `atlas_orient` | query | default 3, maximum 8 |
| `atlas_cards` | batch | minimum 1, maximum 4 |
| `atlas_read` | one-subject | — |
| `atlas_links` | one-subject | default 12, maximum 50 |
| `atlas_provenance` | batch | — |
| `atlas_navigate` | query | — |
| `atlas_define` | query | — |
| `atlas_decisions` | query | — |

- `atlas_orient` turns ordinary design vocabulary into candidate identities
  with status and hook. A miss and a roadmap-only match are both successful
  payloads, not errors.
- `atlas_cards` reads 1–4 distinct canonical ids as one Card each — hook,
  status, the publisher's decision-bearing claims, and compact source
  addresses. It never re-ranks or filters the sealed claims.
- `atlas_read` resolves one canonical address: a bare Node id returns the
  complete Node, `node#section` returns one exact Section, and
  `decision:<id>` returns one complete Decision record. The complete Node is
  the most expensive payload on the surface.
- `atlas_links` pages one subject's relationship occurrences, inbound and
  outbound in the same page. There is **no direction filter** — each
  occurrence carries its own `direction`, so read the side you want off the
  page you already have.
- `atlas_provenance` expands a Card's compact source addresses into publisher
  and attestation facts. Audit is charged separately, so no ordinary payload
  carries it.
- `atlas_navigate` with `view="tree"` walks the canonical ordered traversal,
  never re-ranked by relevance; `view="tour"` returns the publisher-curated
  first tour with the guide's narration. `atlas_define` defines one admitted
  glossary term, reporting an
  exact match, an ambiguity with candidate terms, or a miss.
- `atlas_decisions` lists or searches the admitted decision summaries; read a
  listed record through its `decision:<id>` address. Decision records explain
  history and never override the live Release. A Release that seals no tour
  answers `path: null`, a successful payload rather than a refusal.

## The four rules that govern every call

**Direct address.** The tools are ordered by cost, not by sequence. An
identity you already hold reaches the lowest sufficient payload in one call —
there is no orient-then-card-then-read toll. Orient exists for callers that
do not yet have an identity.

**Batching is atomic.** `atlas_cards` and `atlas_provenance` take a batch and
answer whole or not at all: one duplicated, unadmitted, or roadmap-disclosed
id fails the request with `batch_not_atomic` and returns no cards. Drop the
offending id and re-batch; do not fall back to one call per id.

**Recovery is declared, not guessed.** Every payload states the fact classes
it withheld and, for each, the single operation and address that recovers it.
Claims come back from `atlas_cards`, sections and the node from `atlas_read`,
occurrences from `atlas_links`, audit facts from `atlas_provenance`. Follow
the declared address instead of inferring a next rung — the recovery is the
same call whichever payload omitted the class.

**Revisions are carried, never crossed.** Every payload names the Release it
was read from. Pass that value back as `expected_revision` on every later
call of the same consultation, and pass any continuation cursor back
unchanged — a cursor is bound to the Release it was minted on. If a promotion
lands mid-traversal, the next call fails `revision_changed` with no payload:
start the consultation again on the new Release rather than stitching two
together.

Failures arrive as tool errors carrying one of five stable codes:
`catalog_unavailable`, `revision_changed`, `invalid_argument`,
`batch_not_atomic`, `internal_error`. Empty results, misses, ambiguity, and
roadmap-only matches are none of these — they are successful payloads.

## Route by question shape

Decide from the question before calling anything.

**Where do I start** — `atlas_navigate` with `view="tour"`, one call. It returns the
publisher's own ordered walk with narration; do not assemble a walk from
the `tree` view plus guesswork when this question is what is being asked.

**One term or one pattern's gist** — `atlas_define` or `atlas_navigate` with
`view="tree"`,
answering from what they return, and at most one `atlas_read` of a named
section if the hook is not enough. For an explicit comparison between named
patterns, put their ids in a single `atlas_cards` call rather than reading
them one at a time.

**A design decision where several patterns plausibly bear** — decomposition,
dispatch boundary, context budget, return shape, verification seam,
persistence — run the consultation method below. State the design problem in
full first: goal, constraints, current shape, and the specific decision being
made. The method answers only what is stated.

## The consultation method

Run this in a subagent if the harness has one, and inline in the same context
if it does not. Dispatch is an optimisation; **the consultation is not
optional**. Never fabricate a dispatch, and never skip the consultation
because dispatch is unavailable.

1. `atlas_orient` on the stated problem's own vocabulary — skipped entirely
   when you already hold candidate ids. Widen `bound` toward 8, or follow the
   cursor, rather than re-querying with synonyms.
2. Select candidates whose hooks bear on the decision. Cast wide; a candidate
   costs one card.
3. `atlas_cards`, four ids at a time, until the candidates are covered.
4. `atlas_read` a `node#section` address for the cards that bear, starting from
   the address a claim names. Read the complete Node by bare id only for
   the one or two the decision turns on. Use `atlas_links` to price a hop
   before paying for it.
5. `atlas_decisions`, followed by `atlas_read` on `decision:<id>`, only when
   publication history bears on the consultation; `atlas_provenance` only
   when a claim has to be audited.
6. Drop candidates that turned out not to bear.

## The shape of the answer

Whether the method ran in a subagent or inline, the consultation that comes
out is bounded and cited:

- One bullet per applicable pattern, most constraining first:
  `- **<pattern name>** ([<id> § <section>](https://agentic-atlas.dev/nodes/<id>#<section>))`,
  then 2–5 sentences on what it prescribes or warns *for this design* — not
  a summary of the node.
- Every substantive published-pattern claim carries that same Markdown
  citation. Its visible `<id> § <section>` address stays intact for
  `atlas_read`, while its link opens that exact Section on the Human site.
- A `Tensions` bullet where applicable patterns pull in different directions.
- Statuses carried honestly: `stable` is settled doctrine, `fleshed` is
  claims-frozen with proofs still pending (say so when you rely on it). A
  roadmap disclosure is unpublished: write only its name and hook with
  "(roadmap — nothing published yet)" and leave it unlinked.
- Never more than two consecutive sentences quoted from a node, and the whole
  consultation under ~80 lines. If nothing bears, say so outright and name
  the two or three nearest nodes with one line each on why they fall short.