Add render reference asset manifest contract

docs/render-reference-asset-manifest.md

@@ -0,0 +1,96 @@
+# Render Reference And Asset Manifest Contract
+
+Markitect models render-aware structure before an optional renderer runs. The
+contract is passive: it records units, requested references, static assets, and
+source maps, but it does not assign final numbering, rewrite links, copy
+assets, or validate renderer output directories.
+
+## Contract Version
+
+- `markitect.render.reference.v1`
+
+The manifest kind is:
+
+```text
+render-reference-manifest
+```
+
+## Render Units
+
+`RenderUnitReference` gives a stable identity to renderable content:
+
+| Unit kind | Typical use |
+| --- | --- |
+| `section` | Headings and TOC entries. |
+| `figure` | Images, charts, diagrams, and captions. |
+| `table` | Markdown or generated tables. |
+| `equation` | Math blocks or equation-like units. |
+| `code-block` | Numbered or referenced code listings. |
+| `custom` | Project-defined numbered units. |
+
+The unit model may carry labels, captions, anchors, source spans, content
+hashes, and numbering intent such as scope or sequence. It intentionally does
+not carry final numbers.
+
+## Cross-References And TOC Planning
+
+`RenderCrossReference` represents a requested link from one source location to
+a target render unit. It records the target unit and requested style, while the
+renderer decides final label text, numbering, and URL rewriting.
+
+`RenderTocEntry` records planned table-of-contents entries by unit id, title,
+level, parent id, and order. The renderer owns final page numbers and links.
+
+## Static Assets
+
+`RenderAssetManifest` is a deterministic list of static assets referenced by
+renderer source. Each `RenderAsset` records:
+
+- source URI or source path
+- name, media type, and extension
+- digest when available
+- logical role
+- copy policy declaration
+- renderer output reference placeholder
+- provenance back to source spans or source adapter attachments
+
+Supported copy policies are `copy`, `embed`, `link`, `preserve`, and `skip`.
+They are declarations for downstream renderers. Core Markitect never copies the
+asset.
+
+`markitect-filter` may provide read-side attachment metadata, such as source
+URI, path, media type, extension, digest, and attachment provenance. Markitect
+can transform that metadata into a render asset entry without making
+`markitect-filter` responsible for rendering.
+
+## Source Maps
+
+`RenderSourceMap` connects Markitect source spans or generated function outputs
+to renderer units and artifact references. This is the bridge from deterministic
+Markdown processing to renderer-owned artifacts:
+
+```text
+source span / function output -> render unit -> renderer source or artifact
+```
+
+The map can reference a Markitect source unit, a document function run, a
+render unit id, an artifact id, or a renderer-owned artifact reference.
+
+## Fake Renderer Integration
+
+`RenderExportRequest` accepts an optional `render_manifest`. The built-in
+`render.fake` adapter echoes the manifest id, asset manifest id, unit counts,
+cross-reference count, TOC count, source-map count, and asset count into result
+and artifact metadata. It still performs no external rendering and has no
+filesystem or network side effects.
+
+See `examples/render/render-reference-manifest.yaml` for a complete manifest
+fixture.
+
+## Repository Boundary
+
+- `markitect-tool` owns these passive contracts and fake-renderer metadata
+  integration.
+- `markitect-filter` owns read-side source asset and attachment metadata.
+- `markitect-quarkdown` owns concrete Quarkdown execution, final numbering,
+  output paths, link rewriting, asset copying, and artifact validation.