create-idocs 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Basem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# create-idocs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```sh
+npm create idocs@latest my-docs
+cd my-docs
+pnpm install
+pnpm dev
+```
+
+Creates an Astro + Starlight site with an example diagram and three scenarios, a GitHub Pages workflow, and a Claude Code skill that knows the diagram format. The folder must not exist or must be empty. The project uses pnpm.

package/dist/chunk-YVMC6WCS.js

@@ -0,0 +1,43 @@
+// src/scaffold.ts
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "node:fs";
+import { basename, resolve } from "node:path";
+var RENAMES = {
+  _gitignore: ".gitignore",
+  "_pnpm-workspace.yaml": "pnpm-workspace.yaml"
+};
+function packageName(folder) {
+  const name = folder.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-._]+|[-._]+$/g, "");
+  return name || "my-docs";
+}
+function scaffold(templateDir, target) {
+  const dir = resolve(target);
+  if (!existsSync(templateDir)) throw new Error(`Template not found at ${templateDir}`);
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    throw new Error(`${dir} is not empty. Choose another folder, or empty it first.`);
+  }
+  mkdirSync(dir, { recursive: true });
+  cpSync(templateDir, dir, { recursive: true });
+  for (const [from, to] of Object.entries(RENAMES)) {
+    if (existsSync(resolve(dir, from))) renameSync(resolve(dir, from), resolve(dir, to));
+  }
+  const name = packageName(basename(dir));
+  const file = resolve(dir, "package.json");
+  const pkg = JSON.parse(readFileSync(file, "utf8"));
+  pkg.name = name;
+  writeFileSync(file, `${JSON.stringify(pkg, null, 2)}
+`);
+  return { dir, name };
+}
+
+export {
+  packageName,
+  scaffold
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import {
+  scaffold
+} from "./chunk-YVMC6WCS.js";
+
+// src/index.ts
+import { dirname, join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+var HELP = `create-idocs: start a docs site with interactive architecture diagrams
+
+Usage
+  npm create idocs@latest [folder]
+  pnpm create idocs [folder]
+
+The folder must not exist or must be empty. The project uses pnpm.
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  let target = args.find((a) => !a.startsWith("-"));
+  if (!target) {
+    if (process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      target = (await rl.question("Where should the project go? (my-docs) ")).trim() || "my-docs";
+      rl.close();
+    } else target = "my-docs";
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  const templateDir = join(here, "..", "template");
+  const { dir, name } = scaffold(templateDir, target);
+  const where = relative(process.cwd(), dir) || ".";
+  console.log(`
+Created ${name} in ${where}
+`);
+  console.log("Next:");
+  if (where !== ".") console.log(`  cd ${where}`);
+  console.log("  pnpm install");
+  console.log("  pnpm dev\n");
+  console.log("Then edit diagrams/shop/diagram.yaml and watch the page reload.");
+  console.log("No pnpm? npm install -g pnpm\n");
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/dist/scaffold.d.ts

@@ -0,0 +1,8 @@
+export interface ScaffoldResult {
+    dir: string;
+    name: string;
+}
+/** A valid npm package name for a folder name. */
+export declare function packageName(folder: string): string;
+/** Copy the template into `target`, which must not exist or must be empty. */
+export declare function scaffold(templateDir: string, target: string): ScaffoldResult;

package/dist/scaffold.js

@@ -0,0 +1,8 @@
+import {
+  packageName,
+  scaffold
+} from "./chunk-YVMC6WCS.js";
+export {
+  packageName,
+  scaffold
+};

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "create-idocs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.1",
+  "description": "Scaffold a docs site with interactive diagrams: npm create idocs@latest my-docs",
+  "type": "module",
+  "bin": {
+    "create-idocs": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/scaffold.d.ts",
+      "default": "./dist/scaffold.js"
+    }
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/The-Package-Labs/idocs.git"
+  },
+  "homepage": "https://github.com/The-Package-Labs/idocs#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@the-package-labs/idocs-core": "^0.3.1"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/template/.claude/skills/idocs/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: idocs
+license: MIT
+description: Draw, document and explain systems as interactive architecture diagrams with idocs. Diagrams are YAML files (diagrams/<name>/diagram.yaml) laid out automatically and rendered in an Astro + Starlight docs site, with playable scenarios that show a request travelling through the system. Use when asked to diagram, document or explain a system, service, request path or data flow; to add, change or fix an idocs diagram, scenario or story; when `idocs check` or `pnpm check` reports diagram errors; or to set up an idocs docs site.
+---
+
+# idocs
+
+idocs turns a YAML description of a system into an interactive diagram: readers click a box for its docs, hover to follow connections, and press play on a **scenario** to watch a request travel through the system, as packets over the architecture, as a sequence diagram, or as a swimlane story. You write the model. You never write coordinates; layout is automatic.
+
+## 1. Find out where you are
+
+Look at the project before writing anything.
+
+| You see | Do |
+|---|---|
+| `@the-package-labs/idocs-astro` in `package.json` and a `diagrams/` folder | Authoring. Go to step 2. |
+| An Astro or Starlight site without idocs | Add it: [references/setup.md](references/setup.md), "Add idocs to an existing site". |
+| No docs site at all | Create one: [references/setup.md](references/setup.md), "Start a new site". |
+| The user only wants a picture, with no site | Say that idocs needs a small site to render in, offer to scaffold one, and carry on if they agree. |
+
+Use the project's package manager for every command below (`pnpm idocs ...`, `npx idocs ...`, `yarn idocs ...`). In a project made from the idocs template, `pnpm check` is a shortcut for `idocs check`.
+
+## 2. Authoring workflow
+
+1. **Look at what exists.** `idocs list --json` shows the diagrams, views and scenarios. Extend a diagram rather than starting a second one for the same system.
+2. **Read the code you are documenting.** Never invent components, ports, routes or flows. Put the source files a node is based on in its `refs:` so readers can find them and `idocs check` warns when they move.
+3. **Pick a scope.** One diagram answers one question ("how does checkout work?"). Aim for 8 to 25 nodes. If it needs more, make a second **view** of the same model, not a second diagram.
+4. **Write the model**: nodes, then groups, then edges. Declare nodes in reading order: order decides layout. Format: [references/format.md](references/format.md).
+5. **Add scenarios** for the flows a reader will ask about: the happy path first, then the failures that teach something. Format and writing advice: [references/scenarios.md](references/scenarios.md).
+6. **Check.** `idocs check --json`. Fix every error and every warning; messages carry `file:line:column` and a suggestion. Common ones: [references/troubleshooting.md](references/troubleshooting.md).
+7. **Put it on a page and look at it.** Add `<Diagram name="<name>" />` to an `.mdx` page (see below), run the dev server, and view the page with a browser tool if you have one. A diagram that validates can still look wrong; fix layout with hints: [references/layout.md](references/layout.md).
+
+If you are not sure what a finished diagram looks like, read [assets/examples/shop.diagram.yaml](assets/examples/shop.diagram.yaml). It is complete and is checked by tests.
+
+## The format at a glance
+
+```yaml
+# yaml-language-server: $schema=../diagram.schema.json
+title: Online store checkout
+description: How a shopper's request travels.        # markdown, shown above the diagram
+
+groups:
+  backend: { label: Backend, caption: Kubernetes }
+
+nodes:
+  browser: { kind: client, icon: react, title: Shopper browser }
+  api:
+    kind: service                 # default icon and colour (list in references/format.md)
+    icon: nodejs                  # a name, logos:x, lucide:x, or ./file.svg
+    title: catalog-service
+    sub: ":4001 · Node.js"        # mono line under the title
+    status: planned               # built (default) | planned | legacy | optional
+    in: backend
+    refs: [services/catalog/server.ts]
+  db: { kind: database, icon: postgresql, title: PostgreSQL, in: backend }
+
+edges:
+  - browser -> api: HTTPS         # shorthand: from -> to: label
+  - { from: api, to: db, kind: data, label: SQL, auth: password }
+
+scenarios:
+  browse:
+    title: Browse a product
+    steps:
+      - browser -> api: GET /products/42     # flies along the edges, hop by hop
+      - api -> db: { label: SELECT, kind: lookup }
+      - db -> api: rows                       # flying against an edge makes it a response
+      - api -> browser: 200 OK
+```
+
+Click-through documentation for a box goes in `diagrams/<name>/nodes/<id>.md` (markdown, tables and code fences work). Long scenarios can live in `diagrams/<name>/scenarios/<id>.yaml`.
+
+On a page (`src/content/docs/*.mdx`):
+
+```mdx
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+<Diagram name="shop" />
+<Diagram name="shop" scenario="browse" mode="story" />
+```
+
+## Conventions that make diagrams good
+
+- **Titles are the names people use in conversation.** `sub` carries the technical detail: port, stack, version.
+- **Edge labels are short**: a protocol, a route, an event name. Detail goes in `payload:` and `auth:`.
+- **Mark unbuilt work `status: planned`**, never only in prose. It draws dashed and readers can hide it.
+- **One story per scenario.** Show failure paths as their own scenarios (`payment-declined`), not as footnotes.
+- **Steps: one verb each**, label what travels (`POST /orders`, `order.created`), explain why in `note:`. Group into two to five phases with plain titles ("Submit", "Charge", "Finish").
+- **Do not restate the diagram in prose on the page.** Use the page for what the diagram cannot say: why a choice was made, what to watch for, who to ask.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `idocs check [root...] [--json] [--strict]` | Validate every diagram. `--strict` also fails on warnings. |
+| `idocs list [--json]` | Diagrams, views, scenarios. |
+| `idocs icons search <query>` | Find an icon name (`postgresql`, `logos:redis`, `lucide:server`). |
+| `idocs new <name>` | Scaffold `diagrams/<name>/`. |
+| `idocs schema` | Write `diagrams/diagram.schema.json` so editors autocomplete and validate the YAML. |
+
+## Before you say you are done
+
+- [ ] `idocs check --strict` passes with no errors or warnings.
+- [ ] Every node and flow comes from the code or from the user, not from a guess.
+- [ ] The page renders and the diagram is readable at its default zoom. If it is tiny, it has too much in it.
+- [ ] Planned work is marked `status: planned`.
+- [ ] Each scenario tells one story and has a one-sentence `summary`.

package/template/.claude/skills/idocs/assets/examples/shop.diagram.yaml

@@ -0,0 +1,164 @@
+# A complete, valid diagram that uses most of the format. Checked by the test suite.
+# yaml-language-server: $schema=../diagram.schema.json
+title: Online store
+description: |
+  How a shopper's request reaches the store and what the backend does with it.
+  Pick a scenario above the diagram and press play.
+
+groups:
+  backend:
+    label: Backend
+    caption: Kubernetes · namespace shop
+    rows:                                  # explicit rows, top to bottom
+      - [gateway]
+      - [catalog, cart, orders]
+      - [stores]
+  stores:
+    label: Data and messaging
+    in: backend
+    layout: row                            # packed cards; they need no arrows of their own
+
+nodes:
+  browser:
+    kind: client
+    icon: react
+    title: Shopper browser
+    sub: React storefront
+  cdn:
+    kind: external
+    icon: cloudflare
+    title: CDN
+    sub: static assets · TLS
+  gateway:
+    kind: gateway
+    icon: nginx
+    title: API gateway
+    sub: ":443"
+    lines: [verifies the JWT, routes by path]
+    in: backend
+  catalog:
+    kind: service
+    icon: nodejs
+    title: catalog-service
+    sub: ":4001 · Node.js"
+    uses: [redis, postgres]
+    in: backend
+  cart:
+    kind: service
+    icon: go
+    title: cart-service
+    sub: ":4002 · Go"
+    in: backend
+  orders:
+    kind: service
+    icon: dotnet
+    title: order-service
+    sub: ":4003 · .NET"
+    uses: [postgres, rabbitmq]
+    in: backend
+  redis:
+    kind: cache
+    icon: redis
+    title: Redis
+    sub: catalog cache
+    w: 132
+    in: stores
+  postgres:
+    kind: database
+    icon: postgresql
+    title: PostgreSQL
+    sub: orders · products
+    w: 132
+    in: stores
+  rabbit:
+    kind: queue
+    icon: rabbitmq
+    title: RabbitMQ
+    sub: order.events
+    w: 132
+    in: stores
+  stripe:
+    kind: external
+    icon: stripe
+    title: Stripe
+    sub: payment provider
+  notifier:
+    kind: worker
+    icon: lucide:mail
+    title: notification-worker
+    status: planned                        # drawn dashed, with a PLANNED tag
+
+edges:
+  - browser -> cdn: HTTPS
+  - cdn -> gateway
+  - gateway -> catalog: /products
+  - gateway -> cart: /cart
+  - gateway -> orders: /orders
+  - { from: orders, to: stripe, kind: channel, label: charge, auth: API key, payload: payment intent }
+  - { from: rabbit, to: notifier, kind: queue, status: planned }
+  # Relationships scenarios need but the picture does not: not drawn until a scenario uses them.
+  - { from: catalog, to: redis, kind: data, hidden: true }
+  - { from: catalog, to: postgres, kind: data, hidden: true }
+  - { from: orders, to: postgres, kind: data, hidden: true }
+  - { from: orders, to: rabbit, kind: queue, hidden: true }
+
+views:
+  overview:
+    title: Overview
+    keys: true                             # letter keys on edges
+    interfaces: true                       # a table of every edge under the diagram
+  backend:
+    title: Backend only
+    include: [backend, stripe]
+    direction: DOWN
+
+scenarios:
+  browse:
+    title: Browse a product
+    summary: The catalogue answers from the cache, so the database is never touched.
+    steps:
+      - browser -> catalog: GET /products/42     # flies browser → CDN → gateway → catalog
+      - catalog -> redis: { label: GET product:42, kind: lookup }
+      - redis -> catalog: { label: hit, note: A hit is served in about a millisecond. }
+      - catalog -> browser: 200 + JSON           # flies back against the edges: a response
+
+  place-order:
+    title: Place an order
+    mode: story                              # opens as a swimlane story; Flow and Sequence stay available
+    summary: The order is saved first, charged second, and announced last.
+    lanes:
+      - { title: Shopper, nodes: [browser] }
+      - { title: Order service, sub: .NET, nodes: [orders] }
+      - { title: Stores, sub: Postgres · RabbitMQ, nodes: [postgres, rabbit] }
+      - { title: Payments, nodes: [stripe] }
+    phases:
+      - title: Save
+        caption: before any money moves
+        steps:
+          - browser -> orders:
+              title: Submit the order
+              detail: POST /orders
+              note: The request carries an idempotency key, so a retry cannot charge twice.
+          - orders -> postgres: { label: INSERT order (pending), kind: lookup }
+          - postgres -> orders: saved
+      - title: Charge
+        steps:
+          - orders -> stripe: { title: Charge the card, detail: create payment intent }
+          - at stripe: { title: Authorise, detail: the one step we do not control }
+          - stripe -> orders: succeeded
+      - title: Finish
+        steps:
+          - par:                             # these two start together
+              - orders -> postgres: { label: mark paid, kind: lookup }
+              - orders -> rabbit: { label: order.created, kind: event }
+          - orders -> browser: { title: Confirm, detail: 201 Created }
+
+  declined:
+    title: Card declined
+    summary: Stripe refuses the card. The order stays pending and the shopper is told why.
+    steps:
+      - browser -> orders: POST /orders
+      - orders -> stripe: create payment intent
+      - stripe -> orders: { label: card_declined, kind: error }
+      - at orders: { label: keep order pending, kind: error }
+      - orders -> browser: { label: 402 Payment Required, kind: error }

package/template/.claude/skills/idocs/references/format.md

@@ -0,0 +1,123 @@
+# diagram.yaml reference
+
+One file per diagram: `diagrams/<name>/diagram.yaml`. The folder name is what `<Diagram name="...">` refers to.
+
+```
+diagrams/
+  diagram.schema.json          editor autocomplete (idocs schema)
+  <name>/
+    diagram.yaml               the model, views and scenarios
+    nodes/<node-id>.md         shown when a reader clicks that node (markdown)
+    scenarios/<id>.yaml        optional: a long scenario in its own file; the file name is its id
+```
+
+Top-level keys: `title` (required), `description`, `nodes` (required), `groups`, `edges`, `views`, `scenarios`, `kinds`, `edgeKinds`. Unknown keys are errors with a "did you mean" hint.
+
+## Nodes
+
+`nodes:` is a map from id to node. Ids use letters, digits, `_`, `.` and `-`. A bare string is a title: `api: Catalog service`.
+
+| Field | Meaning |
+|---|---|
+| `title` | Display name. Defaults to the id. |
+| `sub` | One mono line under the title: port, stack, version. |
+| `lines` | List of short body lines in the card. |
+| `icon` | `postgresql` (looks in brand logos, then monochrome brand marks, then Lucide), `logos:redis`, `simple-icons:keycloak`, `lucide:server`, or a path to your own SVG relative to the diagram folder. |
+| `kind` | Gives a default icon and colour family (list below). |
+| `family` | Accent colour: `blue amber violet green teal red slate`. Overrides the kind's. |
+| `in` | Id of the group the node sits in. |
+| `status` | `built` (default), `planned`, `legacy`, `optional`. Non-built nodes draw dashed with a tag. |
+| `badge` | A number or short string shown on the card corner. |
+| `uses` | List of short tags drawn as "uses: a · b". Entries that match a node id become links in the drawer. |
+| `chips` | Small boxes inside the card, such as virtual hosts: `- { label: app.*, sub: "→ backend :9100" }`. |
+| `w` | Card width in px (default 178). Narrow it in dense rows. |
+| `description` | Markdown for the detail drawer, inline. |
+| `doc` | Path to a markdown file for the drawer. Defaults to `nodes/<id>.md` when that file exists. |
+| `links` | `- { label: Runbook, url: https://... }` |
+| `refs` | Source files or URLs the node is based on. `idocs check` warns when a path no longer exists. `src/api.ts`, `src/api.ts:40` and `src/api.ts#L40` all work. |
+| `tags` | Free-form tags. |
+
+Node kinds: `client user ui external service gateway worker container function database cache storage queue agent network vm auth monitor`. Add or override your own with a top-level `kinds:` map: `ledger: { icon: lucide:book-open, family: amber }`.
+
+## Groups
+
+`groups:` is a map from id to group. A top-level group is a filled zone; a group with `in:` is a dashed frame inside another.
+
+| Field | Meaning |
+|---|---|
+| `label` | Required. Shown in capitals in the zone's corner. |
+| `caption` | Muted text after the label: network, runtime, namespace. |
+| `in` | Parent group id. |
+| `layout` | `flow` (default: automatic), `row` or `grid`: pack members tightly. Use for stores and other cards that need no arrows of their own; arrows to a member end on the group's border. |
+| `columns` | Column count for `grid` (and wrapping for `row`). |
+| `rows` | Explicit rows of member ids, top to bottom: `rows: [[proxy], [auth, api], [stores]]`. Each row is spread across the group's width. Members must be direct children of the group. |
+| `direction` | `AUTO` (default), `RIGHT` or `DOWN`: flow direction inside a top-level group. |
+| `family`, `status`, `icon` | As for nodes. |
+
+More on layout choices: [layout.md](layout.md).
+
+## Edges
+
+`edges:` is a list. Forms:
+
+```yaml
+edges:
+  - browser -> cdn: HTTPS                       # from -> to: label
+  - api <-> cache                               # arrows at both ends
+  - { from: api, to: db, kind: data, label: SQL, auth: password, payload: queries }
+  - { from: api, to: audit, hidden: true }      # not drawn until a scenario uses it
+```
+
+| Field | Meaning |
+|---|---|
+| `from`, `to` | Node ids (required in the object form). |
+| `label` | Short: a protocol, route or event name. |
+| `kind` | Line style: `http` (default), `channel` (persistent: websocket, gRPC), `tunnel`, `queue`, `ws`, `data`, or one you define in `edgeKinds:`. |
+| `both` | Arrow at both ends (same as `<->`). |
+| `hidden` | Not drawn and not in the legend, but scenarios can fly along it. Use it for relationships a scenario needs and the picture does not. |
+| `status` | As for nodes. |
+| `key` | A letter shown on the edge and in the interfaces table. Views with `keys: true` assign them for you. |
+| `auth`, `payload`, `transport` | Columns in the interfaces table. |
+| `note` | Markdown. |
+| `id` | Optional; defaults to its position. |
+
+Custom edge kinds: `edgeKinds: { grpc: { label: gRPC, color: accent, width: 2, dash: "6 4" } }`. `color` is a theme token (`ink accent tunnel muted ok warn bad`) or any CSS colour.
+
+In flow-style `{ ... }` maps, **quote any value that contains a comma or `: `**: `{ label: "device → URL, org", kind: lookup }`.
+
+## Views
+
+Without `views:` there is one view with everything. Add views to show different slices of the same model.
+
+```yaml
+views:
+  overview:
+    title: Overview
+    keys: true            # letter keys on edges
+    interfaces: true      # table of every edge under the diagram (key, from → to, kind, auth, payload)
+    summary: Markdown shown above the diagram.
+  backend:
+    title: Backend only
+    include: [backend, stripe]    # node or group ids; a group includes its members
+    exclude: [metrics]
+    direction: DOWN               # AUTO (default), RIGHT, DOWN, LEFT, UP
+```
+
+Edges whose two ends are both in the view are included. A scenario plays on the first view unless it sets `view:`; every node it uses must be in that view.
+
+## Pages
+
+```mdx
+import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+<Diagram name="shop" />                                  # first view, overview
+<Diagram name="shop" view="backend" />
+<Diagram name="shop" scenario="checkout" mode="story" />  # mode: flow | sequence | story
+<Diagram name="shop" showDescription />                  # the diagram's `description`
+```
+
+Other props: `maxHeight` (px, default 780), `showTitle`. Readers can link to a moment with `#<diagram>=<scenario>[.<step>]`, for example `#shop=checkout.3`.
+
+## Theming
+
+Every colour and font is a CSS variable starting `--idocs-` (for example `--idocs-accent`, `--idocs-zone`, `--idocs-sans`, `--idocs-dim` for how faded unrelated items get). Override them under `.idocs` in the site's CSS, and under `:root[data-theme='dark'] .idocs` for dark mode.

package/template/.claude/skills/idocs/references/layout.md

@@ -0,0 +1,39 @@
+# Layout
+
+Layout is automatic, and you steer it with hints, never with coordinates. If a diagram looks wrong, change the model or add a hint, then look again.
+
+## How it works, briefly
+
+Each top-level group (a **zone**) is laid out on its own, in whichever of left-to-right or top-to-bottom comes out squarer. Zones and ungrouped nodes are then arranged side by side. Edges that cross between zones are routed afterwards around the boxes. Two things follow:
+
+- **Declaration order matters.** It decides the order of cards within a layer and which edges count as "backwards". Declare nodes in reading order: entry points first, stores last.
+- **Zones are the unit of layout.** Group related nodes into zones (`groups:`) so they travel together.
+
+## The hints
+
+| Hint | Use it for |
+|---|---|
+| `rows: [[a], [b, c], [d]]` on a group | A stack you want exactly as drawn: gateway, then services, then stores. Each row is spread across the zone's width. Members must be direct children. |
+| `layout: row` or `layout: grid` (with `columns:`) on a group | Cards that need no arrows of their own, such as a row of data stores or a grid of services. Arrows to a member end on the group's border. |
+| `direction: DOWN` or `RIGHT` on a view | Force the main direction. The default `AUTO` tries both and keeps the one that reads larger. |
+| `direction:` on a top-level group | Force the flow direction inside one zone. |
+| `w: 132` on a node | A narrower or wider card (default 178). Narrow the cards in dense rows so a row of five stores does not make the zone huge. |
+| `hidden: true` on an edge | Keep a relationship out of the picture but available to scenarios (service to queue, service to audit log). |
+| A second `view` with `include:` | Show a slice: the backend only, one team's part, one device. |
+
+## Symptoms and fixes
+
+| You see | Try |
+|---|---|
+| The whole diagram is tiny at default zoom | Too much in one picture. Move detail into a second view, hide minor edges, or split the system. Aim for 8 to 25 nodes. |
+| One zone is much wider than the rest | A long row of cards. Narrow them with `w:`, use `layout: grid` with `columns: 2` or `3`, or wrap with `rows:`. |
+| Arrows cross all over | Reorder the nodes so the flow reads one way. Move cards that many things connect to into a packed group (`layout: row`) with a `uses:` tag instead of drawing every edge. |
+| A zone is tall and thin | Set its `direction: RIGHT`, or break a long chain with `rows:`. |
+| Two cards should sit side by side but do not | Put them in one `rows:` row. |
+| An arrow stops at a group border instead of the card | That is how packed groups (`row`, `grid`) work. Put the connected cards in a `flow` group or a `rows` group. |
+| Planned work clutters the picture | Mark it `status: planned`. Readers get a "Hide planned" toggle. |
+| Labels overlap | Shorten them; move detail into `payload:` and `auth:`. |
+
+## When to stop adjusting
+
+If a diagram needs more than a few hints, the model is probably too big for one picture. Split it into views of the same model, or into two diagrams, before reaching for more hints.