docs(design): cmk:visualize, draft plus repo-map specification

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.

[harrymove-ctrl]

Two commits. The first adds docs/design/visualize.md, the feature-level draft for a new cmk:visualize skill. The second adds docs/design/visualize-repo-map.md, which specifies one material type in depth: a map of a repository's own architecture, traced from its real code.

The skill

Renders content someone already has, a design doc, a tracker query, or a description given inline, into something reviewable. It renders, it does not invent. Deciding what to build stays with cmk:design, cmk:requirements, and cmk:adr.

Pipeline: Source Resolver → Form Selector → Renderer.

What the repo-map doc adds

1. A fourth source kind, the repository's own code, handled by a Repo Analyzer that reads docs/ai/ only as a routing hint and gathers a fresh file:line for every node and edge in the run.
2. A scene-graph contract as the waist of the design. The model emits one validated JSON document and nothing else; fixed renderers draw it. Citations are enforced by JSON Schema, so an uncited node or edge fails validation rather than reaching a picture.
3. Four independent form axes: diagram type, visual style, altitude, output form. Three visual styles and the static SVG become four consumers of one dataset rather than four generators.
4. Altitude by node budget (twelve to twenty buildings) with a named-subsystem override, plus eager drill-down to a depth cap. Everything folded is recorded and rendered, never silently truncated.
5. Secret redaction at sample time, since payload sampling reads real snippets out of real files.
6. A website playground with three knobs and twelve pre-rendered assets produced by the real renderer, so the demo cannot drift from what the skill emits.

Scope calls

System Architecture is the only diagram type in v1. Process Flow and AI / Data Flow share the analysis pass and slot in later without rework. The broader diagram-generator surface (IoT scenes, travel routes, teaching diagrams, product structure) is recorded in a later checklist with a note that it cannot reuse the analysis pass and would likely be a separate skill.

Consequences worth flagging to a reviewer

1. This would be the kit's first code-carrying skill. Every existing skill is markdown only. The renderer lives in skills/visualize/assets/ and must be vanilla, offline, and build-free, because cmk:agent-vendors forbids a package referencing anything outside itself by relative traversal. Compatible with cmk:sync as-is, since content_hash already covers all files in a package.
2. Two implementation plans, not one. The playground consumes the skill's output, so it cannot start until the skill emits a real scene graph.

Status: draft

Open points recorded in the docs: trigger phrases, the drill-down depth cap, node-budget calibration against real repos, and the absence of any upstream requirements doc.