feat(export): portal export and web surface [roadmap:v0.11.0]

[tcballard]

Summary

Implements rac/roadmaps/v0.11.x-portal/v0.11.0-portal-export.md.

Adds:

• rac export — a deterministic JSON corpus payload (default mode) and, with --html, the Lore Portal: one self-contained HTML file of the whole corpus that opens from file:// with zero network requests.
• The reconciled viewer contract (lore-web/VIEWER_CONTRACT.md, v1): the lore-web viewer now consumes exactly what Core emits, and the built viewer shell is vendored into the Python package with recorded provenance and a drift-guard test.
• The lore-web web surface this branch developed en route: design system + primitives, a prerendered landing page (open-source framing, real recorded demo, real mascot), and a build-to-artifact CI workflow with no publish step.
• 22 export tests (golden, round-trip, determinism, boundaries, drift guard), README usage documentation, changelog entry, and the registry manifest bump to 0.11.0.

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.11.x-portal/v0.11.0-portal-export.md

Relevant ADRs:

• rac/decisions/adr-012-open-core-strategy.md — import/export are open core
• rac/decisions/adr-014-viewer-agnostic-knowledge-artifacts.md — Core exports data; viewers are interchangeable consumers
• rac/decisions/adr-007-json-contract-stability.md — the payload is a public, golden-tested contract
• rac/decisions/adr-002-ai-optional.md, adr-032 — offline, stateless, deterministic
• rac/decisions/adr-029-guide-delivery-surface.md, adr-031 — ships as a rac subcommand, consumes Core in-process, read-only

Scope

Included

• rac export [directory] [--json | --html] [--out PATH]: service (rac.services.export), output layer (rac.output.portal, render_export_json), CLI wiring, package data for the vendored shell.
• Payload v1: string schema_version; corpus with name, rac_version, artifact_count; artifacts with id, aliases, type, status, title, path, body_html in path order; relationships as relates-to edges sorted by (from, to) with unresolved references preserved verbatim.
• Viewer reconciliation: alias-preferred display and citation linkification, case-insensitive status handling, provenance line, sample corpus regenerated to v1.
• Shell vendoring with provenance.json (lore-web commit, shell hash, normative viewer source-tree hash) and a Python drift-guard test that re-implements the hash and instructs re-vendoring on divergence.
• Web surface: token design system (lantern amber, contrast-verified at 4.5:1 or better), six primitives, landing page (prerendered at build time, Lighthouse 99/100 performance, 100 accessibility), export viewer shell, lore-web-build.yml CI (artifact upload only).

Excluded

• No graph visualisation in the Portal (explicitly deferred by the viewer contract).
• No supersedes/refines/implements edge typing — Core's relationships are family-grouped but semantically untyped; richer types are a future Core decision, not an export invention. The viewer accepts an open set, so the schema is forward-compatible.
• No generated_at timestamp in the payload — would break byte-determinism; revisit with an explicit flag if provenance-in-payload is ever needed.
• No hosted or multi-tenant viewing; the trust boundary is the repository. body_html is rendered by Core with raw HTML escaped and the viewer renders it as-is.
• No deployment of the lore-web site: CI builds to an artifact only.
• No changes to the Guide tool surface.

Product / Architecture Decisions

• The Portal ships as vendored package data, not a Python-native renderer: Core produces data; the shell is an inert byte string with one substitution seam (an empty JSON data element with id lore-export), keeping presentation out of Core per ADR-014 while reusing the verified viewer. Drift risk is covered by the provenance hash test.
• markdown-it-py's commonmark preset enables raw HTML (CommonMark spec behaviour), contrary to the roadmap's assumption — the implementation disables HTML explicitly, and a test pins that a raw script tag in a source body arrives entity-escaped in body_html.
• JSON is the default CLI mode (the payload is the product); --html overwrites an existing --out because exports are build artifacts (stated in --help), unlike rac new which never overwrites.
• status falls back to "unknown" and title to the canonical id where absent — the viewer contract pins strings; rac inspect semantics are otherwise reused (canonical_value against the spec).
• Unknown-type files are skipped (and not counted in artifact_count), mirroring rac index; classification stays separate from validation, so invalid-but-recognizable artifacts export as classified.
• The injected payload escapes the close-tag and comment-open character sequences using standard JSON string escapes, so the embedded document parses unchanged while staying safe inside its host element.
• Naming: the MCP server is the Guide; the exported HTML viewer is the Portal. The v0.11.x roadmap series starts here.

User-Facing Contract

CLI

rac export rac/                                  # canonical JSON to stdout
rac export rac/ --html --out lore-export.html    # the Portal, one file

Human Output

• --html prints exactly one confirmation line: wrote lore-export.html — 121 artifact(s), 323 relationship(s).

JSON Output

{
  "schema_version": "string — \"1\", matching the index contract",
  "corpus": "name (directory basename), rac_version, artifact_count",
  "artifacts": "id, aliases (canonical first), type, status, title, path, body_html",
  "relationships": "from, to (resolved id or literal reference), type (relates-to)"
}

Exit Codes

• 0: export written/emitted (including an empty corpus)
• 2: usage/IO error — missing directory, unwritable --out, --out without --html, missing or corrupt vendored shell seam

Verification

Ran

pytest                                   # 1062 passed (post-merge with v0.10.6)
ruff check src/ tests/ && ruff format --check src/ tests/ && mypy src/
rac validate rac/                        # PASS, 121 valid
rac relationships rac/ --validate        # 0 issues
rac review rac/                          # no priority 1-2 findings
rac export rac/ && rac export rac/ --html --out /tmp/portal.html

Covered

• Golden JSON against a fixture corpus (version monkeypatched for byte-stability); two runs byte-identical.
• HTML round-trip: embedded payload equals --json output; shell byte-identical around the seam; payload script-safe (close-tag and comment-open sequences escaped).
• Boundaries: missing directory exits 2; empty corpus yields a valid empty payload; unresolved reference preserved verbatim; raw HTML in a source body arrives escaped.
• Drift guard matches provenance.json and skips outside the repository checkout.
• Headless Chromium opened the exported Portal of this repository from file://: zero console errors, zero network requests, filters and citation cross-links working.

Review Path

1. src/rac/services/export.py — the payload model and composition of existing Core services
2. src/rac/output/portal.py, src/rac/output/json.py — seam injection and JSON rendering
3. src/rac/cli.py — command wiring and exit codes
4. tests/test_export_cmd.py, tests/fixtures/export/, tests/golden/export_json.txt
5. lore-web/VIEWER_CONTRACT.md, lore-web/src/viewer/ — the reconciled consumer
6. src/rac/templates/portal/ — vendored shell + provenance (generated; review the manifest, skim the shell)
7. README.md, CHANGELOG.md, server.json, rac/roadmaps/v0.11.x-portal/

Notes For Reviewer

• src/rac/templates/portal/lore-portal-shell.html is a generated artifact (~950 KB; source of truth in lore-web/); regenerate with cd lore-web && npm run vendor:shell.
• The branch also carries the lore-web landing-page work (design system, prerendered landing, recorded demo). It is inert from the package's perspective — nothing outside lore-web/ and the CI artifact workflow references it — but it is in the diff.
• main's v0.10.6 (anonymous usage sharing) is merged in; conflicts were limited to the CHANGELOG and the cli.py exit-code docstring, resolved by keeping both entries.
• Tagging v0.11.0 after merge completes the release; the package version is tag-derived (setuptools-scm) and server.json is already bumped.
• Deferred follow-ups recorded in the roadmap: graph visualisation, typed edges, payload timestamps.

Implementation Process

Implemented with AI assistance under the roadmap contract.

Final scope, review, and acceptance decisions were made by the maintainer.