refactor: converge Helm to a local-first personal artifact library

.gitignore

@@ -3,6 +3,15 @@ __pycache__/
 *.py[codz]
 *$py.class
 
+# Helm: the library is LOCAL and PERSONAL — never commit artifacts. This repo is
+# public; artifacts (which may be internal/confidential) stay on the local disk
+# only. catalog.json is derived (rebuild with `helm index`).
+library/*
+!library/.gitkeep
+
+# Personal report outputs dropped at the repo root — never commit to this public repo
+/*.html
+
 # Helm-local design and generated artifact working files
 assets/drafts/
 /*-current-state-*.html

AGENTS.md

@@ -1,21 +1,32 @@
-# Helm artifact handoff
-
-Start by reading [`docs/CODEX-MEMORY.md`](docs/CODEX-MEMORY.md). If the current agent platform offers repository-scoped persistent memory, inject its **Memory payload** at that scope; otherwise reread the checked-in file at the start of each task. Do not put tokens, credentials, private artifacts, or machine addresses into project memory.
-
-For any AI-generated HTML that is meant to be retained, read [`AI-GUIDE.md`](AI-GUIDE.md), [`docs/REPORT-DESIGN-STANDARD.md`](docs/REPORT-DESIGN-STANDARD.md), and the full [`docs/HTML-DOCUMENT-SPEC.md`](docs/HTML-DOCUMENT-SPEC.md) before writing it. Produce one complete, self-contained `HDOC/1.0` file; do not submit Markdown fragments, partial drafts, or executable HTML. The report must be answer-first: make the route from question or decision to evidence, interpretation, and next action or boundary visible rather than producing a landing-page-style document.
-
-For a substantial report, do not imitate the visual style from prose alone. Run `scripts/helm-report list`, select the closest Profile, scaffold the report with `scripts/helm-report new`, and bind each important relationship to a registered component. Replace all specimen content, remove every `placeholder` marker, and make `scripts/helm-report check output.html` pass before submission. The rendered vocabulary is in [`authoring/component-gallery.html`](authoring/component-gallery.html).
-
-For a local clone, run this once before the first handoff:
-
-```bash
-scripts/helm-agent-bootstrap --agent-name "your-agent-name"
-```
-
-Then submit the final file exactly once after local validation:
-
-```bash
-scripts/helm-submit output.html --source "your-agent-name"
-```
-
-Run the submission from the target Codex/project root. Helm records that workspace as the artifact's catalog project when the source manifest does not already declare `project`; if needed, pass `--project-id` and `--project-name` explicitly. The command only hands the artifact revision to the owner's inbox. It does not grant direct access to the browser library. Keep the same manifest ID when revising the same logical artifact; Helm preserves distinct bytes as immutable revisions and asks the owner before advancing the current version. Use a new ID for a different document or explicit fork. On `422`, correct the HDOC contract violation before resubmitting.
+# Helm artifact handoff (for agents)
+
+You are producing a durable HTML report for a person to read and keep. The
+target is one **self-contained `HDOC/1.1` file** in Helm's cool-grey design
+system, dropped into a local folder.
+
+1. Read [`skill/SKILL.md`](skill/SKILL.md) for the workflow, and
+   [`skill/design-system.md`](skill/design-system.md) before writing any HTML.
+   Look at [`skill/components.html`](skill/components.html) for the rendered
+   component vocabulary. Do not imitate the visual style from prose alone.
+2. Inventory the claims first: label each material relationship (comparison,
+   sequence, hierarchy, magnitude, composition, uncertainty, claim strength,
+   action) and its evidence state, then bind each to the smallest component.
+3. Scaffold and fill:
+
+   ```bash
+   bin/helm new "Decision-relevant title" --type report --source your-agent-name
+   # edit $HELM_LIBRARY/<slug>/index.html — replace EVERY specimen,
+   # remove every `placeholder`, delete unused components.
+   bin/helm check $HELM_LIBRARY/<slug>/index.html   # must pass
+   bin/helm index
+   ```
+
+Set `$HELM_LIBRARY` (or run `bin/helm init` once) so any agent knows the target
+folder. No `bin/helm`? Copy `skill/template.html` and edit the inline
+`application/helm+json` manifest by hand.
+
+Produce one complete, answer-first document — not Markdown, not a fragment, not a
+partial draft. Keep the manifest `id` stable when revising the same logical
+artifact; use a new id for a different document. Do not add a dependency on a
+host app, external script, remote asset, or network service. Do not reintroduce
+sharing, publishing, or a server — the library is local and personal by design.

AI-GUIDE.md

@@ -1,56 +1,41 @@
-# HTML generation guide for agents and other projects
+# HTML generation guide for agents
 
-For Codex-style agents, begin with [`docs/CODEX-MEMORY.md`](docs/CODEX-MEMORY.md). It contains the repository-scoped context to inject when the host supports project memory, plus the deterministic handoff workflow when it does not.
+Everything an agent needs is in [`skill/`](skill/). This file is the short
+pointer; the skill is the standard.
 
-Before generating any HTML intended for this repository, read [`docs/HTML-DOCUMENT-SPEC.md`](docs/HTML-DOCUMENT-SPEC.md) in full and comply with `HDOC/1.0`. Then read [`docs/REPORT-DESIGN-STANDARD.md`](docs/REPORT-DESIGN-STANDARD.md). Use [`scripts/helm-report`](scripts/helm-report) to select a report Profile and compose registered visual components instead of recreating a report from prose instructions.
+- [`skill/SKILL.md`](skill/SKILL.md) — the authoring workflow, step by step.
+- [`skill/design-system.md`](skill/design-system.md) — the cool-grey engineering
+  identity: tokens, typography, three content widths, and the component grammar.
+- [`skill/template.html`](skill/template.html) — the standalone scaffold with the
+  full embedded CSS and an inline `HDOC/1.1` manifest.
+- [`skill/components.html`](skill/components.html) — rendered specimens of every
+  component.
 
-The output must be a complete standalone `.html` document — not Markdown, a component, or a code fragment. Include the Helm manifest, the duplicate `helm:*` metadata, semantic `<main data-document-root>`, embedded essential styles, and factual provenance. Put the current Codex/project workspace in the optional `manifest.project` object (`id` + recognizable `name`) so Helm can group the artifact at project level before type and tags. Use the templates in [`templates/`](templates/) as working examples.
+## The contract in one screen
 
-Design direction: calm, evidence-forward report. The artifact should optimize for reading and later recovery, not landing-page conversion. Lead with the reader's question and the short answer; make the path through evidence, interpretation, and the next action or boundary explicit. Before writing HTML, inventory the material claims and label each important relationship: comparison, sequence, hierarchy, magnitude, composition, uncertainty, claim strength, comparable cases, or action/checkpoint. Bind every relationship to the smallest registered component and declare that Claim–component mapping in `manifest.presentation.claims`. Use inline SVG or semantic HTML/CSS, not a runtime chart library or decorative image; each component needs a named claim, evidence state, source/method, scope boundary, and text/table fallback. Keep sources, data dates, assumptions, and confidence near the claims they qualify. Do not add dependencies on a host application, external scripts, authentication, or untrusted executable code.
+The output is a complete standalone `.html` document — not Markdown, a component,
+or a fragment. It must contain:
 
-## Agent authoring workflow
+- an inline manifest `<script type="application/helm+json">…</script>` with at
+  least `id`, `title`, `type`;
+- a semantic `<main data-document-root>`;
+- embedded essential CSS — no external script, stylesheet, font, or remote image
+  (embed images as `data:` URIs);
+- provenance for factual claims kept next to the claim.
 
-List the available Profiles and components:
+Design direction: a calm, evidence-forward report, optimized for reading and
+later recovery — not landing-page conversion. Lead with the reader's question and
+the short answer; make the path through evidence, interpretation, and the next
+action or boundary explicit. Inventory the material claims, label each important
+relationship, and bind it to the smallest registered component. Every component
+needs a named claim, an evidence state, a source/method, a scope boundary, and a
+text/table fallback.
 
-```bash
-scripts/helm-report list
-```
-
-Start from the closest Profile. Profiles supply a useful default composition; `--components` may replace it when the claim inventory requires another grammar. Use `deep-dive` when a long, chaptered report benefits from presentation-like pacing: it adds a sticky chapter index and CSS-only scroll entry while keeping every component readable without animation.
-
-```bash
-scripts/helm-report new \
-  --profile benchmark \
-  --title "Decision-relevant title" \
-  --id stable-artifact-id \
-  --project-id project-workspace \
-  --project-name "Project workspace" \
-  --output output.html
-```
-
-Replace every outlined specimen with real content, update its `data-evidence-state`, `data-source`, and `data-scope`, and remove the `placeholder` class. Do not preserve a component whose underlying relationship is absent. Do not leave a material relationship prose-only merely because the Profile omitted it. Then run:
+Validate before you finish:
 
 ```bash
-scripts/helm-report check output.html
+bin/helm check output.html   # or $HELM_LIBRARY/<slug>/index.html
 ```
 
-The check must pass before `helm-submit`. The rendered component catalog is [`authoring/component-gallery.html`](authoring/component-gallery.html).
-
-## Report preflight
-
-Before returning the file, verify that a reader can see the following without interaction:
-
-1. The document type, title, date/status, and decision-relevant purpose.
-2. The short answer, recommendation, or current finding before long background.
-3. Evidence that supports the conclusion, distinguished from interpretation.
-4. The action, owner/checkpoint, caveat, or open question that follows from the evidence.
-5. Provenance for factual claims: source, date, method, assumption, or confidence as appropriate.
-6. Every material relationship has the smallest useful visual treatment — comparison, evidence route, flow, boundary diagram, metric, or range — or an explicit reason it does not need one.
-
-The authoring CLI is the default starting point for substantial artifacts. The files in `templates/` remain compact examples and compatibility starters; use `research`, `benchmark`, `architecture`, `decision`, `handoff`, or `deep-dive` Profiles when the result needs deliberate visual evidence.
-
-## Optional automatic handoff to Helm
-
-For a fresh local clone, run [`scripts/helm-agent-bootstrap`](scripts/helm-agent-bootstrap) once. Then write the final `.html` file first and submit that exact file once with [`scripts/helm-submit`](scripts/helm-submit). Run the command from the target project root so the Bridge can attach that workspace to legacy files that do not yet declare `manifest.project`; use `--project-id` and `--project-name` when the working directory is not the target project. Do not send partial drafts. A successful Bridge response means the artifact is ready in the owner's **Agent inbox** for explicit review and import; it does not mean the browser library was changed.
-
-Never expose the token in a generated artifact, repository, task log, or prompt. Reuse the manifest ID only for a revision of the same logical artifact; Helm appends distinct bytes as an immutable Revision and never overwrites the prior source. Use a new ID for a different document or explicit fork. On `422`, fix the reported HDOC contract issue and resubmit the same intended artifact.
+Then place the file in the library and run `bin/helm index`. See
+[`AGENTS.md`](AGENTS.md) for the handoff steps.

CONTRIBUTING.md

@@ -5,30 +5,30 @@ Thank you for improving Helm. The project is small by design, so a focused chang
 ## Before you start
 
 1. Read [`README.md`](README.md) and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
-2. For retained HTML or agent workflows, read [`AGENTS.md`](AGENTS.md), [`AI-GUIDE.md`](AI-GUIDE.md), and the full [`docs/HTML-DOCUMENT-SPEC.md`](docs/HTML-DOCUMENT-SPEC.md).
-3. Keep the original HTML immutable. Catalog metadata is an overlay; it is never a silent source-file rewrite.
+2. For the artifact contract and agent workflow, read [`AGENTS.md`](AGENTS.md), [`AI-GUIDE.md`](AI-GUIDE.md), [`docs/HDOC-SPEC.md`](docs/HDOC-SPEC.md), and the authoring standard in [`skill/`](skill/).
+3. Keep artifacts local and personal. The library is the filesystem; this repo never carries generated artifacts.
 
 ## Local verification
 
 ```bash
-python3 -m unittest discover -s tests -p 'test_*.py'
-python3 helm_share_server.py --host 127.0.0.1 --port 4173
+python3 -m unittest discover -s tests -p 'test_*.py'   # CLI + HDOC contract
+bin/helm check <file>                                  # validate one artifact
+bin/helm serve --port 4180                             # http://127.0.0.1:4180/gallery/
 ```
 
-Open the local app and, when a change affects HTML validity or repair behavior, visit `/tests/contract-smoke.html` and `/tests/repair-smoke.html`. Both should show `passed`.
-
 ## Pull-request expectations
 
 - Explain the user-visible outcome and the preserved invariant.
 - Keep unrelated formatting and generated artifacts out of the change.
 - Add or update a focused regression test for behavioral changes.
-- Do not commit Bridge tokens, browser IndexedDB data, private artifacts, machine addresses, or generated local reports.
-- Do not add remote scripts, runtime CDNs, or executable HTML to a retained artifact without a documented and reviewed reason.
+- **Never commit a generated artifact.** Library files and root-level report HTML are gitignored precisely because they may contain internal or confidential content and this repo is public.
+- Do not add remote scripts, runtime CDNs, external fonts, or executable HTML to an artifact — `helm check` enforces self-containment.
+- Preserve the local-first, zero-dependency guarantee. No framework build, server database, or cloud dependency.
 
 ## Design bar
 
-Helm is a calm, evidence-forward research workbench, not a generic file manager or marketing page. Visuals must clarify a real comparison, flow, boundary, or uncertainty; they must not be decoration. See [`docs/REPORT-DESIGN-STANDARD.md`](docs/REPORT-DESIGN-STANDARD.md).
+Helm is a calm, evidence-forward research workbench, not a generic file manager or marketing page. Visuals must clarify a real comparison, flow, boundary, or uncertainty; they must not be decoration. See [`skill/design-system.md`](skill/design-system.md).
 
 ## Reporting a security issue
 
-Do not include credentials or private artifacts in a public issue. For a vulnerability that could expose a local library, Bridge token, or shared document, use GitHub's private vulnerability-reporting channel when it is available; otherwise contact the repository owner privately before publishing technical details.
+Do not include credentials or private artifacts in a public issue. For a vulnerability that could expose a local library or a private document, use GitHub's private vulnerability-reporting channel when it is available; otherwise contact the repository owner privately before publishing technical details.