diff --git a/.claude/rules/rill-html-output.md b/.claude/rules/rill-html-output.md index e97cce1..2ceb932 100644 --- a/.claude/rules/rill-html-output.md +++ b/.claude/rules/rill-html-output.md @@ -24,6 +24,7 @@ The commit boundary is regenerability, not class: anything that can be rebuilt f 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`). + The dot prefix hides `.view/` from the AI only (search, resume); the GUI's reading surface still lists its contents under a Read shelf, so a derived render is never invisible to the person it was rendered for (ADR-086). 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 `` 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.