rill-html-output-doctrine-rule: add vault-wide HTML output rules

.claude/commands/_close/analysis-agent.md

@@ -12,7 +12,7 @@
 - `output_language` (optional): ISO 639-1 language code for narrative output fields (e.g. `"ja"`, `"en"`); when omitted, default to English
 - `style_guide` (optional): short vocabulary-boundary rules for narrative fields (see Language section); when omitted, write narrative fields in plain English
 
-**Read the metadata file and all numbered deliverables (NNN-*.md) before starting analysis.**
+**Read the metadata file and all numbered deliverables (NNN-*.md) before starting analysis.** Committed HTML-canonical artifacts (e.g. `NNN-*.html` mocks and diagrams with no same-basename MD source — see `rill-html-output.md`) are deliverables too: read their content like any other deliverable, since the HTML is their only record. Skip only derived HTML regenerable from MD sources (`.view/` sidecars, same-basename `.html` twins of an MD file).
 
 ## Language
 
@@ -39,7 +39,8 @@ You MUST NOT:
 
 1. Read the metadata file (`_workspace.md` / `_session.md` / `_project.md`)
 2. Read every `NNN-*.md` file in the workspace directory (in parallel if possible)
-3. Do NOT rely on summaries — read full contents
+3. Read every committed HTML-canonical artifact (`NNN-*.html` etc. with no same-basename MD source) — the HTML is its only record, so analyze it like any other deliverable and carry it into `## Deliverables`. Skip only derived HTML regenerable from MD sources (`.view/` sidecars, same-basename `.html` twins of an MD file) — `rill-html-output.md` principle 3
+4. Do NOT rely on summaries — read full contents
 
 ## Phase 2: Generate _summary.md
 

.claude/rules/rill-claude-code-integration.md

@@ -26,7 +26,7 @@ rill mkfile tasks --slug review-contract --type task
 rill mkfile pages --slug rill-roadmap --type page
 ```
 
-Exceptions: system files without frontmatter (`.claude/rules/*.md`, subdirectory `CLAUDE.md`); editing existing files (use Edit tool).
+Exceptions: system files without frontmatter (`.claude/rules/*.md`, subdirectory `CLAUDE.md`); editing existing files (use Edit tool); generated HTML files (no frontmatter — producing skills write them directly, see `rill-html-output.md`).
 
 ## GUI Integration: show paths, don't auto-navigate
 

.claude/rules/rill-core.md

@@ -41,6 +41,7 @@ Personal voice journal + knowledge management system. Core flow: **voice / text
 - **tasks/**: [rill-tasks.md](rill-tasks.md) — status, due/scheduled, subtasks
 - **projects/**: [rill-projects.md](rill-projects.md) — execution hub layer (ADR-080)
 - **reports/ + pages/**: [rill-outputs.md](rill-outputs.md) — Daily Note, Newsletter, recipe pairs
+- **HTML output**: [rill-html-output.md](rill-html-output.md) — Markdown-canonical doctrine, HTML classes, read-moment generation, commit policy
 - **Claude Code integration**: [rill-claude-code-integration.md](rill-claude-code-integration.md)
 - **Autonomous execution**: [rill-autonomous-execution.md](rill-autonomous-execution.md) — lanes, Plan gate, worktrees, Codex usage, two-channel write, three-tier destructive ops
 

.claude/rules/rill-data-model.md

@@ -35,6 +35,8 @@ Common frontmatter schema, references, links. Directory-specific rules: `rill-in
 
 Use `rill mkfile` for new files (ADR-060) — ensures timestamp accuracy. LLMs never write `created` directly. See `rill-claude-code-integration.md`.
 
+**HTML exception**: generated HTML files carry no frontmatter and are not created via `rill mkfile` — producing skills write them directly; derived views embed a provenance comment instead. See [rill-html-output.md](rill-html-output.md).
+
 ## `source:` Read Priority
 
 When reading a `source:` file, prefer the same-named file in `_organized/` if present. Example: `source: inbox/meetings/2026-02-16-X.md` → if `inbox/meetings/_organized/2026-02-16-X.md` exists, Read that.

.claude/rules/rill-html-output.md

@@ -0,0 +1,71 @@
+# HTML Output Rules — Rill
+
+Markdown is the vault's canonical format; HTML is how humans read it. This rule defines when HTML files exist in a vault, where they live, how they are named, what gets committed, and what the AI reads on resume. Layer rules (`rill-outputs.md`, `rill-workspace.md`, `rill-tasks.md`) defer to this file for HTML policy.
+
+The underlying asymmetry: AI reads and writes long Markdown cheaply; humans absorb a structured HTML page far better than a wall of Markdown. The vault therefore keeps two layers — Markdown as the machine-facing source of truth, HTML as the human-facing reading surface — and never lets the second layer become a write surface.
+
+## HTML Classes
+
+Every HTML file in a vault belongs to one of four classes:
+
+| Class | Role | MD canonical? | Typical examples | Git |
+|---|---|---|---|---|
+| **A. Derived view** | Human-readable projection of one or more MD sources; regenerable | Yes | `.view/` digests, handbooks, book reading views (`rill book build`); same-basename report twins | `.view/` sidecars gitignored; same-basename twins committed |
+| **B. Primary HTML** | The HTML *is* the deliverable; no MD twin | No | UI mocks, architecture / comparison diagrams, plugin templates | Committed |
+| **C. Judgment / handoff surface** | Presents a decision, status, or walkthrough to the user | Either | Decision digests, run digests, plan reviews, meeting runbooks | Committed unless generated as a `.view/` sidecar |
+| **D. External presentation** | Material for people outside the vault | Either | Meeting handouts, client-facing documents | Committed (archival) |
+
+The commit boundary is regenerability, not class: anything that can be rebuilt from MD sources on demand lives in a `.view/` sidecar and stays out of git; anything that is a deliverable in its own right is committed. Two deliberate exceptions are regenerable yet committed for archival value: committed archival twins (same-basename report twins, principle 6), and class D external deliverables generated from MD — handed to people outside the vault, so the shipped version is preserved in git even though it could be rebuilt.
+
+## Global Principles
+
+1. **Markdown canonical.** Every internal artifact with an MD source keeps Markdown as its source of truth. Diagrams embedded in derived views keep their source (Mermaid, SVG) on the MD side so the AI can edit them.
+2. **Derived HTML is read-only.** HTML generated from MD sources (class A, and class C/D when derived) is never hand-edited and never a write-back target — edits go to the MD source and the view is regenerated. Class B — and any class C/D file authored without an MD source — is the exception: the HTML file *is* the source, and the AI creates and revises it directly when asked. Skill search globs stay `.md`-scoped in all cases.
+3. **Resume reads MD only.** `/focus`, `/solve`, `/distill`, and any other resume path Read `.md` files; the skip applies to derived HTML — anything regenerable from MD sources — which is never loaded into AI context during resume or search. HTML-canonical artifacts (class B, and class C/D authored without an MD source) are the exception: when resuming work that targets such an artifact, the agent reads it, because the HTML is the only record of its current state; resumes not targeting it still skip it. (Working directly on a specific HTML deliverable at the user's request likewise reads that file.)
+4. **No HTML-only information in derived output.** Views generated from MD sources may reorder, summarize, and teach, but must not carry substantive information absent from those sources — reading the MD always yields full context. Files whose HTML is the source (class B, source-less C/D) are exempt by definition.
+5. **Naming.** Regenerable derived views — single- or multi-source — go into a `.view/` directory next to their sources (dot-prefixed: invisible to listings and AI search); `.view/` placement is the default for any render not kept as an archival deliverable. A committed archival twin (the deliberate exception in the commit boundary above, e.g. a report twin) swaps the extension in place (`foo.md` → `foo.html`, same directory, same basename). Standalone class B/C/D files use normal artifact naming (`NNN-{desc}.html`).
+6. **Commit policy** (revised 2026-08, supersedes the earlier "commit all HTML, never gitignore" decision, which shipped implementation reversed — ADR-085). Primary and handoff HTML (classes B, C, D) is committed. Derived `.view/` sidecars are gitignored (`**/.view/` in the managed `.gitignore` block) and regenerated on demand. Committed class A twins are allowed where archival value exists but must honor principle 4.
+7. **Expressiveness is unconstrained (L0).** No mandated template; the AI chooses presentation per context. The only hard constraints are technical. Self-containment: a single-page render is one self-contained file (styles inline, no external network dependencies); a multi-page `.view/` view is self-contained at the directory level — relative references to co-located assets and sibling pages are allowed, but nothing outside the view directory tree beyond its MD sources. Current `rill book build` output predates this requirement (it leaves remote image URLs in place and links local images outside the view directory) and is exempt until the builder embeds or copies assets; new generators must meet it. Provenance: derived views identify their source and generator via a head comment `<!-- generated from {md_path} @ {timestamp} by {skill} -->` or equivalent generator metadata (e.g. a `generator` meta tag plus a visible footer attribution, as `rill book build` emits). These constraints govern pages generated at read moments; persistent generation templates (`plugins/{name}/templates/`) are generation sources, not generated pages — new templates should avoid external network dependencies, but templates that predate this rule are exempt until next revised.
+8. **Generation failure is non-fatal.** If HTML generation fails, the producing skill still succeeds with Markdown alone.
+
+## When HTML Is Generated
+
+HTML is generated at **read moments** — the points where a human reads in order to judge — not continuously and not as a 1:1 mirror of every MD file. The table below is the doctrine's target wiring: `rill book build` is shipped; the `/focus`, `/close`, and `/project` generation steps are wired into those skills progressively. Until a producer implements its step, that read moment is served on explicit user request.
+
+| Read moment | Producer | Output |
+|---|---|---|
+| Decision point during a live session | `/focus` | Decision digest snapshot → `workspace/{id}/.view/` (dated; a snapshot serves that one read moment and is disposable afterwards — the judged content and the decision record live in MD, so losing the sidecar loses nothing durable) |
+| Workspace completion | `/close` | Aggregated handbook (single or multi-page) → `workspace/{id}/.view/` |
+| Project review (status / end of an autonomous run) | `/project` | Project digest with pending decisions → `projects/{slug}/.view/` |
+| Book reading | `rill book build` | Fixed-style reading view → `pages/{id}/.view/` |
+| Explicit user request | any skill | Ad-hoc render, placed per the class rules above |
+
+Two anti-patterns this model replaces:
+
+- **1:1 mirroring** — generating an HTML twin for every MD artifact produces unread files and constant regeneration cost.
+- **Continuous regeneration during a volatile phase** — a live-updated view of work still in flux rots the moment it is built. While content is volatile, Markdown is the working surface; a dated snapshot generated at the read moment is always correct *as of that moment*.
+
+Staleness is handled by regeneration at the next read moment, never by hooks that chase every MD edit.
+
+## Layer-by-Layer Operations
+
+| Layer | Default | HTML appears as | Class | AI resume reads |
+|---|---|---|---|---|
+| `inbox/` (all types) | MD only | Handout derivative under `_organized/` (ad-hoc) | C/D | MD (`_organized/` preferred) |
+| `knowledge/` | MD only | Never | — | MD |
+| `workspace/{id}/` | MD artifacts | Mocks / diagrams as committed artifacts; digests and handbooks under `.view/` | B; A/C | `.md`; an HTML-canonical artifact only when it is the resumed work's target (principle 3) |
+| `tasks/{slug}/` | MD artifacts | Ad-hoc plan / review / guide renders | C | MD |
+| `projects/{slug}/` | MD | Project digest under `.view/` | A/C | MD |
+| `pages/` | MD (human-canonical documents) | Book reading view under `pages/{id}/.view/` | A | — (pages excluded from AI search) |
+| `reports/` | MD | Optional same-basename twin (`{date}.html`, committed, ad-hoc) | A | MD |
+| `plugins/{name}/templates/` | HTML templates | Persistent generation sources | B | — (expanded at runtime) |
+| `.claude/`, `docs/`, `taxonomy.md`, `activity-log.md` | MD only | Never | — | MD |
+
+HTML files carry no frontmatter and are not created via `rill mkfile` — producing skills write them directly (`rill-data-model.md`, `rill-claude-code-integration.md`).
+
+## Cross-Reference
+
+- `rill-outputs.md` — reports/ and pages/ specifics, including books and `rill book build`
+- `rill-workspace.md` — file-first principle; workspace artifact conventions
+- `rill-tasks.md` — task artifact conventions
+- ADR-085 — pages as human-canonical documents; the `.view/` gitignored sidecar

.claude/rules/rill-outputs.md

@@ -8,6 +8,8 @@ paths:
 
 `reports/` and `pages/` are the **output layer** — Claude Code-generated artifacts and human-facing aggregated documents.
 
+HTML derivatives in this layer (same-basename report twins, book reading views under `.view/`) follow the vault-wide HTML policy in [rill-html-output.md](rill-html-output.md): Markdown stays canonical, derived `.view/` sidecars are gitignored, and the AI reads `.md` only.
+
 ## reports/
 
 ```

.claude/rules/rill-tasks.md

@@ -18,7 +18,7 @@ tasks/
 
 Each task is a directory so /solve can accumulate research notes, plans, decisions under it without spawning a workspace. Simple tasks remain a one-file directory.
 
-Sub-directories under a task are not allowed (flat artifact layout). Binary artifacts (HTML mock, image, PDF) may live at the same level as `_task.md`.
+Sub-directories under a task are not allowed (flat artifact layout), with one exception: a `.view/` sidecar directory for regenerable derived renders (gitignored, per [rill-html-output.md](rill-html-output.md) principle 5). Binary artifacts (HTML mock, image, PDF) may live at the same level as `_task.md`. HTML artifacts follow the class rules in [rill-html-output.md](rill-html-output.md) — on resume the AI reads `.md` only, except an HTML-canonical artifact that is itself the resumed work's target (principle 3).
 
 ## File Names
 

.claude/rules/rill-workspace.md

@@ -78,6 +78,10 @@ Save artifacts to files: analyses, research, comparison tables, decisions, frame
 
 Text-only is fine for: brief confirmations / suggestions (1-2 paragraphs), directional discussion, brainstorming, summary preview before saving. When in doubt, write a file — a workspace's value lives in its accumulated artifacts.
 
+### HTML Artifacts
+
+Workspace HTML follows [rill-html-output.md](rill-html-output.md): mocks and diagrams are committed primary artifacts (the HTML is the deliverable, no MD twin); decision digests and completion handbooks are derived views generated into `workspace/{id}/.view/` (gitignored, regenerable). On resume the AI reads `.md` files only — derived HTML is skipped; an HTML-canonical artifact (mock, diagram) is read only when it is itself the resumed work's target (rill-html-output.md principle 3).
+
 ### Updating `_workspace.md`
 
 At each milestone: add new artifacts to "Related Files (MOC)", update checkboxes, append "Session History", update "Next Steps".

skills/close/SKILL.md

@@ -413,7 +413,7 @@ If the /pulse invocation fails, log a 1-line warning to stdout and treat the /cl
 
 - **Never modify `inbox/journal/` and `inbox/*/` original files** (read-only)
 - Knowledge distillation runs in Distillation sub-agents (ADR-073), NOT in parent context. The parent only orchestrates
-- Include frontmatter in all files
+- Include frontmatter in all files (exception: generated HTML files carry no frontmatter and are written directly, not via `rill mkfile` — see `rill-html-output.md`)
 - **Backward compatibility**: also handle workspaces that only have `_session.md` or `_project.md` (treat as metadata file)
 - **Forbidden justifications**: parent MUST reject `pragmatic scope reduction`, `to save time`, `not novel enough`, `context budget running low`, `already sufficient coverage`, and any unlabeled reason. See `.claude/commands/_close/distillation-agent.md` for the authoritative list
 - `uncovered > 0` must trigger a STOP, not a warning. Do not proceed to Phase 6+ with uncovered candidates

skills/focus/SKILL.md

@@ -114,7 +114,7 @@ After session start (or resume), interact with the following flow:
 
 1. Display the metadata file (`_workspace.md` / `_session.md` / `_project.md`) contents to user (overview, issues, next steps)
 2. On resume, collect additional context:
-   - Read deliverables within the workspace
+   - Read deliverables within the workspace — `.md` files only; skip derived HTML (regenerable from MD sources). Read an HTML file only when it is the canonical artifact the resumed work targets, or the user explicitly points at it (`rill-html-output.md` principle 3)
    - Related information from knowledge/notes/ based on tags
    - Recent relevant entries from inbox/journal/
    - Related reports from reports/ (newsletters, dailies, etc.) (ADR-061)
@@ -163,7 +163,7 @@ type: research
 - `_workspace.md` (or `_session.md`) is continuously updated as the session progresses
 - Once created, deliverable files are generally not modified (additions/corrections go in new files)
 - When active workspaces exist, prioritize proposing resume
-- Include frontmatter in all files
+- Include frontmatter in all files (exception: generated HTML files carry no frontmatter and are written directly, not via `rill mkfile` — see `rill-html-output.md`)
 - Prefer `_organized/` version when same-named file exists
 - **Note metadata correction (ADR-046 D46-7)**: When reading knowledge/notes/ files, handle in two modes:
   **Mode A — Direct fix** (no AI judgment needed, 1-2 Edits per fix, < 100ms):

skills/promote/SKILL.md

@@ -99,7 +99,7 @@ By default `/promote` proposes creating a **new project** for the workspace, not
 
 ### Phase 2: Candidate extraction
 
-Read `workspace/{id}/_summary.md` and the workspace directory's artifacts (`NNN-*.md`). Build three candidate lists:
+Read `workspace/{id}/_summary.md` and the workspace directory's artifacts (`NNN-*.md`, plus committed HTML-canonical artifacts — `NNN-*.html` etc. with no same-basename MD source, whose HTML is the only record; skip derived HTML regenerable from MD sources, per `rill-html-output.md` principle 3). Build three candidate lists:
 
 1. **Artifact references** — every artifact file in the workspace, with its `type` (decision / research / analysis / progress / review) and its `# ` heading. These will be linked from the project, not duplicated
 2. **Key findings** (3–5 items) — pull from `_summary.md`'s Decisions / Key Findings section. The user will confirm before they land in `## Key Facts`

templates/AGENTS.md

@@ -10,8 +10,10 @@ directory name. Also read the nearest nested `AGENTS.md` for the target path.
 - Original files under `inbox/` are immutable. Only `_organized/` derivatives
   may be created or changed.
 - Create vault content with `rill mkfile`; never write the `created`
-  frontmatter field manually.
-- Frontmatter is required and must follow `.claude/rules/rill-data-model.md`.
+  frontmatter field manually. For the full file-creation and frontmatter
+  conventions — including file types that carry no frontmatter — follow the
+  auto-updated rule files: `.claude/rules/rill-data-model.md` and
+  `.claude/rules/rill-html-output.md`.
 - Email addresses and phone numbers belong only in `knowledge/people/` or
   `knowledge/orgs/`.
 - Do not edit Rill-managed files listed in `.rill/managed-files.txt`. Change