docs-canvas

Docs canvas

Contract

Field	Bound contract
Trigger	Render a set of documentation (file, directory, or URL) as an interactive, navigable HTML canvas artifact.
Authority	Reversible local: writes only the single output HTML artifact in the working directory; rollback is deleting that file. No remote mutation. Read-only access to local files or network fetch for URLs.
Side effect	Creates one self-contained HTML canvas artifact under the working directory.
Done	One self-contained, navigable HTML file at the stated path containing the structured overview, rendered sections, and a combined sources index.

Inputs

Required: a documentation source. A file path, a directory path, or a URL that is readable from the working directory or reachable over the network.

Optional: a preferred output filename (default docs-canvas.html) and a section-grouping hint.

Procedure

1. Fetch or traverse the documentation source to extract text. For a single file, read it directly. For a directory, walk the tree and read every text-readable file (markdown, HTML, plain text), skipping binary and non-document files. For a URL, fetch the page content. Stop if the source is unreadable or unreachable. Done when: raw text is extracted from every readable source file or page.

2. Parse the extracted text into an ordered hierarchy of document titles and section headings. For each document, extract the title and every heading in source order. When two headings produce the same anchor, disambiguate by appending a numeric suffix. Done when: titles and headings are extracted in source order with unique anchors.

3. Extract source references and build a combined index. Collect every citation, link, and attribution discovered across all documents. Build an index mapping each reference to its source document and location. Done when: the combined sources index is built.

4. Render the content as a single HTML artifact with an interactive table of contents and a combined sources index. Produce one section per heading, preserving the source text without paraphrase or invented content. The table of contents links each entry to its section anchor; the combined sources index links each reference to its source document and location. Done when: every heading has a rendered section, every TOC entry links to its anchor, and the combined sources index is rendered.