@honua/mcp-server 0.1.4-beta.0 → 0.1.8-beta.0

package/dist/src/tools/docs-search.js

@@ -0,0 +1,381 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { capabilityUnavailable } from "../capability.js";
+import { jsonText } from "../helpers.js";
+/**
+ * `honua_docs_search` — answer a documentation question from the repository's
+ * own versioned documentation corpus, with citations.
+ *
+ * The corpus is `llms-full.txt` (generated by `npm run docs:llms`), which
+ * concatenates the documents indexed in `llms.txt` under `# File: <path>`
+ * headers. Every hit therefore carries the exact source file it came from and
+ * the commit those bytes are at (so the citation keeps naming the text that was
+ * actually searched once `trunk` moves), and the version block carries the
+ * release that documentation describes — derived
+ * from `docs/versions.json` when it has been generated
+ * (`npm run docs:versions:write`) and otherwise directly from `package.json` +
+ * `.release-please-manifest.json`, the same authoritative pair
+ * `scripts/docs-versions.mjs` uses. The policy those citations follow is
+ * documented in `docs/documentation-versions.md`.
+ *
+ * This is a LOCAL tool: it reads committed files and never makes a network
+ * request. When the corpus cannot be located (for example inside an installed
+ * `@honua/mcp-server` that does not ship the corpus), it degrades the same way
+ * every other surface-dependent tool does — a structured `available: false`
+ * result with guidance, not a crash and not a misleading empty answer.
+ */
+const REPOSITORY = "honua-io/honua-sdk-js";
+const SITE_URL = "https://honua-io.github.io/honua-sdk-js/";
+const CORPUS_FILE = "llms-full.txt";
+const MAX_EXCERPT_CHARS = 1200;
+const EXCERPT_CONTEXT_LINES = 6;
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
+/**
+ * Function words carry no retrieval signal but appear in every document, so on
+ * a natural-language question ("how do I handle a capability error") they match
+ * everywhere, add frequency weight everywhere, and inflate the matched-term
+ * multiplier everywhere -- which is exactly enough to push `docs/errors.md`
+ * below `docs/guide.md` and out of the default three results. Terms shorter
+ * than two characters are already dropped by the tokenizer.
+ */
+const STOPWORDS = new Set([
+    "about",
+    "all",
+    "an",
+    "and",
+    "any",
+    "are",
+    "as",
+    "at",
+    "be",
+    "been",
+    "but",
+    "by",
+    "can",
+    "do",
+    "does",
+    "doing",
+    "done",
+    "for",
+    "from",
+    "get",
+    "getting",
+    "has",
+    "have",
+    "how",
+    "if",
+    "in",
+    "into",
+    "is",
+    "it",
+    "its",
+    "me",
+    "my",
+    "not",
+    "of",
+    "on",
+    "onto",
+    "or",
+    "our",
+    "should",
+    "so",
+    "some",
+    "that",
+    "the",
+    "their",
+    "them",
+    "then",
+    "there",
+    "these",
+    "they",
+    "this",
+    "to",
+    "up",
+    "use",
+    "used",
+    "using",
+    "via",
+    "want",
+    "was",
+    "we",
+    "what",
+    "when",
+    "where",
+    "which",
+    "who",
+    "why",
+    "will",
+    "with",
+    "would",
+    "you",
+    "your",
+]);
+export const schema = z.object({
+    query: z
+        .string()
+        .min(2)
+        .describe("Natural-language or keyword documentation question, e.g. 'how do I handle a capability error'"),
+    limit: z.number().int().min(1).max(10).optional().describe("Maximum documents to return (default 3)"),
+    pathPrefix: z
+        .string()
+        .optional()
+        .describe("Restrict results to source files whose path starts with this value, e.g. 'docs/' or 'mcp/'"),
+});
+/**
+ * Split `llms-full.txt` into its constituent documents. The generator emits
+ * `# File: <path>` as the delimiter for each concatenated document.
+ */
+export function splitCorpus(corpus) {
+    const documents = [];
+    const pattern = /^# File: (.+)$/gm;
+    const matches = [...corpus.matchAll(pattern)];
+    for (const [index, match] of matches.entries()) {
+        const start = (match.index ?? 0) + match[0].length;
+        const end = index + 1 < matches.length ? (matches[index + 1].index ?? corpus.length) : corpus.length;
+        const body = corpus
+            .slice(start, end)
+            .replace(/\n-{3,}\s*$/, "")
+            .trim();
+        const heading = /^#\s+(.+)$/m.exec(body);
+        documents.push({ file: match[1].trim(), title: heading?.[1]?.trim() ?? match[1].trim(), body });
+    }
+    return documents;
+}
+/**
+ * The terms a query is actually ranked and excerpted on: distinct tokens with
+ * the stopwords removed. A query made entirely of stopwords ("how do I") keeps
+ * its raw tokens rather than degrading to "no indexed document matched", so
+ * filtering can only ever improve a ranking, never empty one.
+ */
+export function queryTermsOf(query) {
+    const tokens = [...new Set(query.toLowerCase().match(/[a-z0-9_./-]{2,}/g) ?? [])];
+    const significant = tokens.filter((token) => !STOPWORDS.has(token));
+    return significant.length > 0 ? significant : tokens;
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+/** Deterministic lexical score: path and heading matches outweigh body matches. */
+export function scoreDocument(document, queryTerms) {
+    const file = document.file.toLowerCase();
+    const body = document.body.toLowerCase();
+    const headings = (document.body.match(/^#{1,4} .+$/gm) ?? []).join("\n").toLowerCase();
+    let score = 0;
+    let matched = 0;
+    for (const term of queryTerms) {
+        const inBody = countOccurrences(body, term);
+        const inHeadings = countOccurrences(headings, term);
+        const inPath = countOccurrences(file, term);
+        if (inBody + inHeadings + inPath > 0)
+            matched += 1;
+        score += Math.min(inBody, 20) + inHeadings * 3 + inPath * 8;
+    }
+    // Require more than a single incidental term hit on multi-term queries.
+    if (matched === 0)
+        return 0;
+    return score * matched;
+}
+/** The most relevant window of a document, trimmed to a token-friendly size. */
+export function excerptFor(document, queryTerms) {
+    const lines = document.body.split("\n");
+    let bestLine = 0;
+    let bestHits = 0;
+    for (const [index, line] of lines.entries()) {
+        const lower = line.toLowerCase();
+        const hits = queryTerms.reduce((total, term) => total + countOccurrences(lower, term), 0);
+        if (hits > bestHits) {
+            bestHits = hits;
+            bestLine = index;
+        }
+    }
+    const start = Math.max(0, bestLine - EXCERPT_CONTEXT_LINES);
+    const end = Math.min(lines.length, bestLine + EXCERPT_CONTEXT_LINES + 1);
+    const excerpt = lines.slice(start, end).join("\n").trim();
+    return excerpt.length > MAX_EXCERPT_CHARS ? `${excerpt.slice(0, MAX_EXCERPT_CHARS)}…` : excerpt;
+}
+/**
+ * Locate the corpus: an explicit `HONUA_DOCS_CORPUS_PATH` (the corpus file
+ * itself, or a directory holding one), otherwise the nearest ancestor directory
+ * holding `llms-full.txt`.
+ *
+ * The override names the file to read, so it is read — its basename is not
+ * assumed to be `llms-full.txt`. Discarding it and reading `<parent>/llms-full.txt`
+ * instead would throw `ENOENT` for a corpus under any other name, or silently
+ * answer from a different sibling file.
+ */
+export function resolveDocsCorpus(env = process.env, from) {
+    const override = env.HONUA_DOCS_CORPUS_PATH;
+    if (override) {
+        const resolved = path.resolve(override);
+        if (!fs.existsSync(resolved))
+            return undefined;
+        const corpusPath = fs.statSync(resolved).isDirectory() ? path.join(resolved, CORPUS_FILE) : resolved;
+        if (!fs.existsSync(corpusPath))
+            return undefined;
+        return { corpusPath, root: path.dirname(corpusPath) };
+    }
+    let dir = from ?? path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth += 1) {
+        const corpusPath = path.join(dir, CORPUS_FILE);
+        if (fs.existsSync(corpusPath))
+            return { corpusPath, root: dir };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** The documentation root holding the corpus, or `undefined` when there is none. */
+export function resolveDocsRoot(env = process.env, from) {
+    return resolveDocsCorpus(env, from)?.root;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function channelOf(version) {
+    const prerelease = version.split("-", 2)[1];
+    return prerelease ? prerelease.split(".", 1)[0] : "stable";
+}
+/**
+ * The release the corpus documents, from the same authoritative sources as
+ * `scripts/docs-versions.mjs`. Prefers the generated `docs/versions.json` and
+ * falls back to `package.json` + `.release-please-manifest.json`.
+ */
+export function resolveDocsVersion(root) {
+    const generated = readJson(path.join(root, "docs", "versions.json"));
+    const packageName = typeof generated?.package === "string" ? generated.package : "@honua/sdk-js";
+    const citation = (version) => ({
+        package: packageName,
+        version,
+        channel: channelOf(version),
+        documentationChannel: "development",
+        policy: "docs/documentation-versions.md",
+        versionsManifest: `${SITE_URL}versions.json`,
+    });
+    if (typeof generated?.latestRelease === "string")
+        return citation(generated.latestRelease);
+    const pkg = readJson(path.join(root, "package.json"));
+    const manifest = readJson(path.join(root, ".release-please-manifest.json"));
+    const version = typeof pkg?.version === "string" ? pkg.version : undefined;
+    const manifestVersion = typeof manifest?.["."] === "string" ? manifest["."] : undefined;
+    if (!version || !manifestVersion || version !== manifestVersion)
+        return undefined;
+    return citation(version);
+}
+function git(root, args) {
+    try {
+        return execFileSync("git", [...args], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The exact commit the searched corpus bytes come from, or `undefined` when it
+ * cannot be established.
+ *
+ * `docs/documentation-versions.md` is explicit that a matching version string
+ * is not proof that development documentation describes the npm artifact, and
+ * that every built page identifies its 40-character source commit. A citation
+ * pinned to `trunk` breaks that: `trunk` moves, and the text a reader is sent
+ * to can stop being the text that was searched. So citations are pinned to the
+ * commit instead, using the same `HONUA_SOURCE_REVISION` override
+ * `scripts/build-docs-site.mjs` honours.
+ *
+ * The commit is only used when the corpus at `HEAD` is byte-identical to the
+ * corpus that was read (`git hash-object` against `HEAD:<path>`). A locally
+ * regenerated or edited `llms-full.txt` is not at any commit, and pinning it to
+ * `HEAD` would produce a citation that looks exact and is wrong. When nothing
+ * can be established — an installed package with no checkout, no `git`, a dirty
+ * corpus — the URL stays on `trunk` and the citation reports
+ * `sourceRevision: null` so the consumer can see the link is floating.
+ */
+export function resolveCorpusRevision(root, corpusPath, env = process.env) {
+    const declared = env.HONUA_SOURCE_REVISION?.trim().toLowerCase();
+    if (declared && COMMIT_PATTERN.test(declared))
+        return declared;
+    const top = git(root, ["rev-parse", "--show-toplevel"]);
+    if (!top)
+        return undefined;
+    const head = git(root, ["rev-parse", "HEAD"])?.toLowerCase();
+    if (!head || !COMMIT_PATTERN.test(head))
+        return undefined;
+    const relative = path.relative(top, path.resolve(corpusPath)).split(path.sep).join("/");
+    if (relative.startsWith(".."))
+        return undefined;
+    const committed = git(root, ["rev-parse", `HEAD:${relative}`]);
+    const working = git(root, ["hash-object", corpusPath]);
+    if (!committed || !working || committed !== working)
+        return undefined;
+    return head;
+}
+function sourceUrl(file, revision) {
+    return `https://github.com/${REPOSITORY}/blob/${revision ?? "trunk"}/${file}`;
+}
+export async function execute(_client, input) {
+    const located = resolveDocsCorpus();
+    if (!located) {
+        return capabilityUnavailable("Honua documentation corpus", `${CORPUS_FILE} was not found in this installation or any parent directory`, "Run `npm run docs:llms` in a honua-sdk-js checkout, or point HONUA_DOCS_CORPUS_PATH at a generated llms-full.txt.");
+    }
+    const { corpusPath, root } = located;
+    const version = resolveDocsVersion(root);
+    if (!version) {
+        return capabilityUnavailable("Honua documentation versions", "package.json and .release-please-manifest.json disagree or are unavailable, so no release can be cited", "Run `npm run docs:versions:write` in a honua-sdk-js checkout so documentation answers can cite a release.");
+    }
+    const documents = splitCorpus(fs.readFileSync(corpusPath, "utf8"));
+    const revision = resolveCorpusRevision(root, corpusPath);
+    const queryTerms = queryTermsOf(input.query);
+    const prefix = input.pathPrefix?.toLowerCase();
+    const results = documents
+        .filter((document) => (prefix ? document.file.toLowerCase().startsWith(prefix) : true))
+        .map((document) => ({ document, score: scoreDocument(document, queryTerms) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.document.file.localeCompare(b.document.file))
+        .slice(0, input.limit ?? 3)
+        .map((entry) => ({
+        title: entry.document.title,
+        score: entry.score,
+        excerpt: excerptFor(entry.document, queryTerms),
+        citation: {
+            file: entry.document.file,
+            url: sourceUrl(entry.document.file, revision),
+            // The commit the cited text was read at. `null` means the URL floats on
+            // `trunk` and the text there may already differ from what was searched.
+            sourceRevision: revision ?? null,
+            package: version.package,
+            version: version.version,
+            channel: version.channel,
+        },
+    }));
+    return jsonText({
+        available: true,
+        query: input.query,
+        release: version,
+        corpus: { file: path.basename(corpusPath), documents: documents.length, sourceRevision: revision ?? null },
+        results,
+        ...(results.length === 0
+            ? {
+                guidance: "No indexed document matched. Try fewer or more specific terms, or drop pathPrefix. An empty result means the corpus has no matching text, not that the capability is missing.",
+            }
+            : {}),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honua/mcp-server",
-  "version": "0.1.4-beta.0",
+  "version": "0.1.8-beta.0",
   "description": "Platform-free MCP server for geospatial services: expose discovery, query, and analysis over any public ArcGIS/Esri FeatureServer or OGC API endpoint to any MCP client, with no platform lock-in",
   "license": "Apache-2.0",
   "author": "Honua",
@@ -23,7 +23,8 @@
   "type": "module",
   "bin": {
     "honua-mcp": "dist/src/index.js",
-    "honua-mcp-proxy": "dist/src/proxy.js"
+    "honua-mcp-proxy": "dist/src/proxy.js",
+    "honua-zero-to-map-release": "dist/src/release/zero-to-map-cli.js"
   },
   "exports": {
     ".": {
@@ -53,6 +54,8 @@
     "certify:standalone-ogc": "npm run build --silent && node dist/src/certification/cli.js --target standalone-ogc",
     "test:certification:nl-map-control": "vitest run test/certification/nl-map-control.test.ts",
     "test:certification": "npm run build --silent && vitest run test/certification && node dist/src/certification/cli.js",
+    "test:certification:admin": "vitest run test/proxy.test.ts test/certification/admin-parity.test.ts",
+    "certify:admin-parity": "npm run build --silent && node dist/src/certification/admin-parity.js",
     "test:certification:artifact": "npm run build --silent && node dist/src/certification/cli.js --artifact-only",
     "test:certification:standalone": "npm run build --silent && node dist/src/certification/cli.js --target standalone",
     "test:certification:standalone-ogc": "npm run build --silent && node dist/src/certification/cli.js --target standalone-ogc",
@@ -64,6 +67,7 @@
     "leaderboard": "node scripts/render-leaderboard.mjs",
     "test:eval": "npm run build --silent && vitest run test/eval && node dist/src/eval/cli.js --offline",
     "test:eval:artifact": "npm run build --silent && node dist/src/eval/cli.js --artifact-only",
+    "release:zero-to-map": "npm run build --silent && node dist/src/release/zero-to-map-cli.js",
     "lint": "biome lint src/ test/",
     "lint:fix": "biome lint --write src/ test/",
     "format": "biome format src/ test/",
@@ -83,7 +87,7 @@
     "fast-uri": "^3.1.3"
   },
   "peerDependencies": {
-    "@honua/sdk-js": "^0.1.4-beta.0"
+    "@honua/sdk-js": "^0.1.8-beta.0"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
@@ -95,6 +99,7 @@
   },
   "files": [
     "dist/src",
+    "release/zero-to-map",
     "certification/geospatial-mcp-schemas",
     "README.md",
     "LICENSE"

package/release/zero-to-map/README.md

@@ -0,0 +1,174 @@
+# Zero-to-map 2026.1 release journey
+
+This bundle is the executable contract for `honua-release#123` D9.3: install
+Honua, configure and publish deterministic data with AI-accessible admin tools,
+run Buffer through the AI-facing Esri MCP tool, the SDK's Esri GPServer
+compatibility path, and the MCP-native analysis verb, compose distinct map,
+app, and dashboard packages in Studio, save each as an immutable version, read
+that exact version, reopen it as a new draft, record three publication intents,
+and save three new intent-bearing versions. It then stops at the human Console
+gate before verifying the three approved public URLs. Both MCP
+jobs are polled through `honua://jobs/{id}` and joined to their
+`honua://jobs/{id}/results` packages; a queued submission alone cannot pass.
+
+The driver reuses `honua admin install` and `honua-mcp-proxy`. It does not ship
+a second installer, admin client, or MCP transport. The installer is the
+canonical credential-issuance boundary: material is handed directly to its
+private environment/MCP configuration files, while its JSON receipt contains
+only the credential ID, requested/effective grants, active status, and a digest
+of the file reference.
+
+## Inspect the contract without changing anything
+
+From the `mcp` package directory:
+
+```sh
+npm run release:zero-to-map -- --output zero-to-map-contract-receipt.json
+```
+
+Contract mode never invokes Docker, CLI, MCP, GPServer, Console, or HTTP. Its
+receipt is intentionally `blocked`, with the first live action blocked and all
+later actions skipped. Static issue references remain under `dependencyRefs`;
+they are never reported as runtime blockers on a passed live receipt.
+
+## Configure an MCP client
+
+The `configs` directory contains equivalent examples for Claude Desktop,
+Claude Code, and Cursor. Each launches the existing `honua-mcp-proxy` and points
+it at the remote MCP endpoint. Set `HONUA_MCP_AUTH_TOKEN` separately when
+the deployment requires bearer authentication; do not put credentials in the
+journey plan or a release receipt.
+Credential-bearing proxy and live-journey endpoints require HTTPS, except for
+exact loopback HTTP used by the bounded local-Docker profile. User information,
+query parameters, fragments, cross-origin redirects, and any catalog that is not
+exactly the enabled-profile roster fail closed before the first mutation.
+
+## Run a live candidate
+
+Prerequisites:
+
+- Node.js 20.19 or newer and Docker with Compose
+- the 2026.1 `honua` CLI work from `honua-sdk-js#1370-#1373`
+- a server build exposing the complete default 432-tool roster (47 static plus
+  385 `honua_admin_*` tools), with all eleven secret/session Admin operations
+  absent, **and** the `analysis` and `esri-gp` server profiles enabled so the
+  three `honua_esri_gp_*` tools and `honua_buffer_features` are advertised
+  (441 tools in total), plus the Studio lifecycle tools including
+  `honua_studio_save_version`, `honua_studio_get_version`, and
+  `honua_studio_reopen_version`
+- the `geoprocessing/Buffer` GPServer task seeded by the deployment
+- these fixtures available to the server at an HTTP(S) base URL
+- a writable checkpoint path; the first pass emits the exact resolved Console
+  receipt request after all pre-approval work completes
+
+Serve the checked-in fixtures from a URL reachable by the Honua container, for
+example with an existing static-file server. Then run:
+
+```sh
+npm run release:zero-to-map -- \
+  --execute --yes \
+  --target local-docker \
+  --mcp-url http://localhost:8080/mcp \
+  --var fixtureBaseUrl=http://host.docker.internal:4173 \
+  --var dbSecretReference=env:HONUA_ZERO_TO_MAP_DB_CONNECTION \
+  --var dbSecretType=environment \
+  --var candidateId=manifest-sha256:<platform-manifest-sha256> \
+  --var releaseId=2026.1 \
+  --checkpoint ./zero-to-map.checkpoint.json \
+  --output ./zero-to-map-live-receipt.json
+```
+
+The first pass exits `2` with `external-receipt-missing`. It has already run
+stages 1-5 exactly once. Give the checkpoint's resolved
+`consoleReceiptRequest` to the Console producer, carry
+`checkpoint.integrity.digest` outside that file, and resume with the same
+command plus:
+
+```sh
+  --checkpoint-digest <checkpoint.integrity.digest> \
+  --console-receipt ./console-approval.json
+```
+
+The resume atomically claims the checkpoint before any adapter work. A second
+or concurrent claimant fails closed. The checkpoint is bound to the exact plan
+bytes, SDK source SHA (`HONUA_SOURCE_REVISION`), target, MCP endpoint,
+candidate/release, and (for AWS) provisioning receipt; it contains only
+allowlisted captures/evidence, including the non-secret deterministic
+`serviceName` identity and access-credential ID/grants/reference digest required
+by external producers, and never the database password, admin key, token, or
+authorization material. A successful resume
+marks it consumed and binds the final receipt hash.
+
+For a deployment already provisioned by the DevOps ECS producer, use
+`--target aws-ecs --provision-receipt <pre-teardown-binding.json>`. The binding
+must match `contracts/aws-ecs-provision-binding.schema.json`, the candidate and
+release variables, and `--mcp-url=<binding.endpoint>/mcp`. Stage 1 then records
+the real image/digest, Terraform, readiness, and a secret-free access receipt
+whose reference digest is verified against the producer's Secrets Manager ARN;
+it does not invoke or pretend to invoke the Docker installer.
+
+The catalog is checked in full before the first MCP call. Missing tools or
+input-schema drift block the run without sending that call.
+
+The preflight verifies each enabled server profile independently and *derives*
+the expected total from them; it never compares the catalog against a single
+hardcoded number:
+
+| Profile | Members | Verified by |
+| --- | --- | --- |
+| `base` | 47 static + 385 `honua_admin_*` = 432 | the generated Admin contract, plus the 11 audited secret/session exclusions proven absent |
+| `analysis` | 6 | `honua_buffer_features` by name; the rest by declared size (the server has not published an `analysis` roster - honua-server#3363) |
+| `esri-gp` | 3 | exactly `honua_esri_gp_list_tasks`, `honua_esri_gp_describe_task`, `honua_esri_gp_execute_task` from `contracts/esri-gp-mcp.v1.json` |
+
+The enabled candidate therefore advertises 432 + 6 + 3 = 441 tools. A missing,
+unexpected, duplicate, excluded, truncated, or schema-drifted member fails with
+its own labelled finding naming the journey stage and action that needs the
+tool; a short catalog is reported as a pagination fault rather than a roster
+decision. The pagination safety ceiling in `listAllTools` is deliberately
+separate from every roster number, so reading a larger profile-enabled catalog
+is never mistaken for a hostile server. Default-profile certification
+(`certifyAdminCatalogParity`) continues to require exactly 432.
+
+The connection is
+created with `secretReference` + `secretType`; raw database credentials never
+enter MCP arguments, checkpoints, or receipts. One-time-secret and session-bound
+operations (including API-key issuance) are deliberately absent from MCP and
+must be handled by the install/control-plane credential boundary. The journey
+then exercises only secret-safe API-key list and effective-permissions tools to
+verify the provisioned identity and its exact grants. Admin operations
+must return a completed PublishedOperation; queued or approval-required handles
+produce explicit blocked receipts. The driver reads connection/layer IDs only
+from `structuredContent.details.response`, the server's PublishedOperation
+endpoint-response seam.
+
+The Studio version tools are also preflighted before the first server mutation.
+Map, app, and dashboard each exercise layer, style, view, widget, and control
+mutations before validation; family-specific shortcuts or embedded lookalikes
+cannot satisfy the release roster.
+The journey does not treat `honua_studio_get_draft` as reopen evidence: every
+family must capture its `itemId`, immutable `versionId`, `contentHash`, and the
+new draft whose `baseVersionId` points back to that exact version. After the
+proposal increments that reopened draft's generation, the journey saves a new
+immutable publication version. Console must create and publish the request for
+that new version, never the earlier pre-intent version.
+
+The Console receipt is accepted only when it is `passed` and binds this
+journey/release contract to the exact connection, service, layers, three GP job
+identities, result packages/artifacts, map/app/dashboard draft and immutable
+version identities, all three reopened drafts and intent-bearing publication
+versions, all three Console request/publication/status/public-URL identities,
+execution operations, audit correlations, routes, candidate, and release. Each
+audit operation must equal its family's execution operation, each proposal ID
+must equal its publication request ID, and the app public URL must equal the
+top-level share URL. The Studio proposal actions reject any pre-approval
+publication ID or public URL and must report both `recorded=true` and
+`humanConfirmationRequired=true`. Agent execution never claims the human
+publication step. Stage 7 independently requires identity-preserving HTTPS
+HTTP 200 responses for map, app, and dashboard URLs.
+
+## Evidence status
+
+The fixtures, plan, contracts, and simulated end-to-end tests are deterministic.
+They are not a live release recording. Until all deployment dependencies are
+available and an operator supplies a matching Console receipt, the honest
+candidate result is `blocked`/`skipped`, not passed.

package/release/zero-to-map/configs/claude-code.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "honua": {
+      "command": "npx",
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.7-beta.0", "honua-mcp-proxy"],
+      "env": {
+        "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
+      }
+    }
+  }
+}

package/release/zero-to-map/configs/claude-desktop.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "honua": {
+      "command": "npx",
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.7-beta.0", "honua-mcp-proxy"],
+      "env": {
+        "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
+      }
+    }
+  }
+}

package/release/zero-to-map/configs/cursor.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "honua": {
+      "command": "npx",
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.7-beta.0", "honua-mcp-proxy"],
+      "env": {
+        "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
+      }
+    }
+  }
+}