diff --git a/README.md b/README.md index 89b886c..cfdeb27 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@

- - stackmap: interactive system diagrams your coding agent writes, as one offline HTML file + + stackmap: every layer of your stack, on one map. Interactive system diagrams your coding agent writes, as one offline HTML file

- A 25-second tour of the viewer on an agent tool call workflow: zoom in and select the planner, open the Approval gate guided view, pick a route from User to Final reply, play the flow hop by hop, then switch to the dark theme + Website · Docs · Examples

Ask your coding agent to diagram a codebase, a system, a process or a request. It writes a small typed JSON, stackmap validates it with repair hints the agent acts on, lays it out, and delivers one self-contained HTML viewer. No server, no account, nothing to install to open it. @@ -27,13 +27,22 @@ Then ask: > Make an architecture diagram of this repository, backed by evidence from the code. +

+ + + The loop: you ask your coding agent, it writes diagram.json, stackmap checks it and names the fix, the agent repairs it, and you open one HTML file + +

+ The agent writes `.stackmap//diagram.json`, validates and repairs it, and delivers `.stackmap//diagram.html`. Open that file in any browser. To change the diagram, ask again: the agent edits the JSON and delivers it again. The viewer itself is read-only. ## The viewer

- stackmap viewer in light mode: a Commerce API topology with the Orders database selected and its upstream traced; the inspector shows its details, connections and source evidence - The same diagram in dark mode + + + A tour of the viewer on the Commerce API diagram: zoom in and select Orders DB to see its connections and source evidence, open the Checkout path view, route from Storefront to Stripe, and play the flow hop by hop +

- **Explore:** select a card for its details, connections and source evidence. **Trace** keeps a node's upstream and downstream; **Route** lights every path between two nodes. @@ -63,11 +72,18 @@ The agent writes `.stackmap//diagram.json`, validates and repairs it, and } ``` +

+ + + A card's parts: the icon tile, up to three stats with a note, a footer with two items and a link; beside it, the six connection styles: a call, async, reply, main path, security crossing and failure path + +

+ - **Nodes:** nine types set the colour (`client`, `gateway`, `service`, `database`, `cache`, `queue`, `storage`, `external`, `security`), and lifecycles have seven state types. Cards can add rows, stats, a footer, a link and one of 146 [Simple Icons](https://simpleicons.org) logos. - **Edges** can be `async` or a `return`, with a `tone` for the main path, security crossings and failure paths. - **No coordinates:** stackmap lays everything out, with [ELK](https://eclipse.dev/elk/) for architecture and dataflow and its own layout for lanes and sequences. -Full reference: [skill/references/schema.md](skill/references/schema.md). Modelling guidance: [authoring contract](skill/references/authoring-contract.md). +Full reference: [skill/references/schema.md](skill/references/schema.md), or the [schema reference](https://stackmap-site.vercel.app/docs/schema) on the website. Modelling guidance: [authoring contract](skill/references/authoring-contract.md). ## The CLI diff --git a/assets/brand/README.md b/assets/brand/README.md index 727f088..80f09fd 100644 --- a/assets/brand/README.md +++ b/assets/brand/README.md @@ -20,7 +20,7 @@ Every file carries explicit colours, so pick the light file or its `-dark` twin | `stackmap-wordmark.svg`, `-dark` | The name alone, where the mark would be under 16px | | `stackmap-app-icon.svg`, `-512.png`, `stackmap-apple-touch-icon-180.png` | The full mark on the near-black icon tile | | `stackmap-favicon.svg`, `-32.png`, `-16.png` | The compact mark on the icon tile (inlined in the viewer) | -| `stackmap-readme-header.svg`, `-dark` | The 1280×320 README header, in a `` at the full column width | +| `stackmap-readme-header.png`, `-dark` | The 1280×400 README header at 2×, in a `` at the full column width | | `stackmap-social-card.png`, `.svg`, `-light.svg` | The 1200×630 link preview (`og:image`, the GitHub social preview) | ## Rules diff --git a/assets/brand/stackmap-readme-header-dark.png b/assets/brand/stackmap-readme-header-dark.png new file mode 100644 index 0000000..6ef37b3 Binary files /dev/null and b/assets/brand/stackmap-readme-header-dark.png differ diff --git a/assets/brand/stackmap-readme-header-dark.svg b/assets/brand/stackmap-readme-header-dark.svg deleted file mode 100644 index adc722c..0000000 --- a/assets/brand/stackmap-readme-header-dark.svg +++ /dev/null @@ -1 +0,0 @@ -stackmap \ No newline at end of file diff --git a/assets/brand/stackmap-readme-header.png b/assets/brand/stackmap-readme-header.png new file mode 100644 index 0000000..8494e1f Binary files /dev/null and b/assets/brand/stackmap-readme-header.png differ diff --git a/assets/brand/stackmap-readme-header.svg b/assets/brand/stackmap-readme-header.svg deleted file mode 100644 index 6013267..0000000 --- a/assets/brand/stackmap-readme-header.svg +++ /dev/null @@ -1 +0,0 @@ -stackmap \ No newline at end of file diff --git a/assets/readme/agent-loop-dark.svg b/assets/readme/agent-loop-dark.svg new file mode 100644 index 0000000..5586d6a --- /dev/null +++ b/assets/readme/agent-loop-dark.svg @@ -0,0 +1,67 @@ +stackmap: from a request to one HTML file1You ask2Your agent writes JSON3stackmap checks it4You open one fileAsk your coding agentMake an architecturediagram of thisrepository, backed byevidence from the code.diagram.json1{2"kind": "architecture",3"nodes": [ … ],4"edges": [ …,5{ "from": "api",6"to":"orders-db" }"orders" }7]8}stackmap · validateerror refs/unknown-node /edges/6/toUnknown node "orders-db"fix: use "orders"fix: add node "orders-db" or remove the edge✗ 1 error✓ valid: no diagnosticsdiagram.htmlfix \ No newline at end of file diff --git a/assets/readme/agent-loop-light.svg b/assets/readme/agent-loop-light.svg new file mode 100644 index 0000000..e0fa1c2 --- /dev/null +++ b/assets/readme/agent-loop-light.svg @@ -0,0 +1,67 @@ +stackmap: from a request to one HTML file1You ask2Your agent writes JSON3stackmap checks it4You open one fileAsk your coding agentMake an architecturediagram of thisrepository, backed byevidence from the code.diagram.json1{2"kind": "architecture",3"nodes": [ … ],4"edges": [ …,5{ "from": "api",6"to":"orders-db" }"orders" }7]8}stackmap · validateerror refs/unknown-node /edges/6/toUnknown node "orders-db"fix: use "orders"fix: add node "orders-db" or remove the edge✗ 1 error✓ valid: no diagnosticsdiagram.htmlfix \ No newline at end of file diff --git a/assets/readme/card-dark.png b/assets/readme/card-dark.png new file mode 100644 index 0000000..2e004ac Binary files /dev/null and b/assets/readme/card-dark.png differ diff --git a/assets/readme/card-light.png b/assets/readme/card-light.png new file mode 100644 index 0000000..0a7de73 Binary files /dev/null and b/assets/readme/card-light.png differ diff --git a/assets/readme/tour-dark.webp b/assets/readme/tour-dark.webp new file mode 100644 index 0000000..5470e2c Binary files /dev/null and b/assets/readme/tour-dark.webp differ diff --git a/assets/readme/tour.webp b/assets/readme/tour.webp index 20df85a..7627be3 100644 Binary files a/assets/readme/tour.webp and b/assets/readme/tour.webp differ diff --git a/assets/readme/viewer-dark.png b/assets/readme/viewer-dark.png deleted file mode 100644 index 8aaba0f..0000000 Binary files a/assets/readme/viewer-dark.png and /dev/null differ diff --git a/assets/readme/viewer-light.png b/assets/readme/viewer-light.png deleted file mode 100644 index 78acbe0..0000000 Binary files a/assets/readme/viewer-light.png and /dev/null differ