create-idocs 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,104 @@
+# Scenarios
+
+A scenario is a story that plays over a diagram: an ordered list of steps. Each step flies a packet along your edges, or makes one node do something. A diagram can have any number of scenarios; readers pick one above the diagram.
+
+## Shape
+
+```yaml
+scenarios:
+  place-order:
+    title: Place an order
+    summary: |                      # the story in one or two sentences (markdown)
+      The order is saved first, charged second and confirmed last.
+    phases:                         # optional chapters; or use a flat `steps:` list
+      - title: Save
+        caption: before any money moves
+        steps:
+          - browser -> orders:
+              label: POST /orders
+              note: The request carries an idempotency key.     # explanation shown in the step list
+          - orders -> db: { label: INSERT order, kind: lookup }
+      - title: Charge
+        steps:
+          - orders -> stripe: create payment intent
+          - at stripe: { label: authorise card, note: The one step we do not control. }
+          - stripe -> orders: succeeded
+```
+
+Only `title` and at least one step are required. Other scenario fields: `view` (which view to play on; default the first), `mode` (`flow`, `sequence` or `story`: how it opens), `lanes` (story columns, below).
+
+## Steps
+
+| You write | What happens |
+|---|---|
+| `a -> b: label` | A packet flies from `a` to `b`. |
+| `at a: label` | `a` pulses and shows the caption: "this component does something". |
+| `par:` with a nested list | The steps inside start together. |
+
+Every step can be written compactly (`a -> b: label`) or as a map (`a -> b: { label: ..., kind: ..., note: ... }`). Options:
+
+| Option | Meaning |
+|---|---|
+| `label` | What travels, shown on the packet. Keep it short. |
+| `kind` | `request` (default), `response`, `error`, `lookup`, `event`. Changes the packet's colour and style. |
+| `note` | Markdown explanation shown in the step list. |
+| `status` | `planned` draws the step dashed with a tag. |
+| `via` | Force the route through these nodes: `via: [gateway]`. |
+| `hold` | Extra pause in seconds. |
+| `title`, `detail` | The heading and short body of the step's box in the story view. |
+
+**Routing.** Steps follow the edges you declared. If `a` and `b` are not directly connected, the packet takes the shortest route through the nodes between them, hop by hop (`browser -> db` flies through the API). If there is no route, `idocs check` says so: declare an edge (it can be `hidden: true`) or add `via`.
+
+**Responses.** A packet that flies against an edge's direction is a response automatically (green), so `db -> api` over an `api -> db` edge needs no `kind`. Write `kind: error` for failures.
+
+**Lookups.** `kind: lookup` marks a quick question to a data store or cache. Follow it with the answer: `cache -> api: hit`.
+
+## Story view
+
+The same scenario can be read as a story: swimlanes with one column per actor, steps running down the page in order, and the phases as bands. Readers switch with the Flow / Sequence / Story buttons; `mode: story` makes it the default.
+
+How steps become boxes:
+
+| Step | In the story |
+|---|---|
+| `at a: ...` | A box in `a`'s lane. |
+| `a -> b: ...` | A box in `b`'s lane, joined by an arrow to the box before it. If the story is not already at `a`, a small box shows where it starts. |
+| `a -> b: { kind: lookup }` | A dashed box in `b`'s lane, level with the step that asked, joined by a double-headed dotted arrow. The answer step that follows is folded into the same box. |
+
+Boxes are numbered 1, 2, 3 along the story; lookups are not numbered. Click a box to play that step.
+
+```yaml
+scenarios:
+  read-request:
+    title: One read request, end to end
+    mode: story
+    lanes:                                # columns, left to right
+      - { title: Browser, nodes: [browser] }
+      - { title: Stores, sub: Redis · Postgres, nodes: [redis, postgres] }    # one lane, several nodes
+    phases:
+      - title: Who are you?
+        steps:
+          - gateway -> backend:
+              title: Check the session    # box heading; defaults to the label
+              detail: |                   # one to three short lines; defaults to "from → to"
+                cookie → session
+                token read from Redis
+          - backend -> redis: { label: session lookup, kind: lookup }
+          - redis -> backend: found
+          - at backend: { title: Which device?, detail: id → URL + org }
+```
+
+- Without `lanes` you get one lane per node, in order of first appearance. With `lanes`, list them in the order you want; nodes you leave out get their own lane at the end, and `idocs check` warns about them.
+- Write `title` as a short question or verb phrase ("Who are you?", "Cross the tunnel") and `detail` as what is concrete: a route, a header, a store. They are for the story only; the packet label stays short.
+- Use `at` steps for "this component does something" moments, and lookups for questions to a data store.
+- Keep a story to about 8 lanes and 15 boxes. Past that, split it into two scenarios.
+
+## Writing good scenarios
+
+- **One question per scenario.** "Pay with a card" and "Card declined" are two scenarios.
+- **Failures get their own scenario.** That is where readers learn the most.
+- **Label what travels** (`POST /payments`, `payment.succeeded`) and put the reasoning in `note`.
+- **Two to five phases**, with plain names. They become the chapter headings in the step list.
+- **Do not narrate the obvious.** A note should answer "why" or "what could go wrong here".
+- **Start at the actor.** The first step is usually `browser -> gateway`, or an `at` step describing the trigger.
+- If a scenario needs a relationship you do not want drawn, add the edge with `hidden: true`.

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

@@ -0,0 +1,95 @@
+# Setting up idocs
+
+idocs renders diagrams inside an **Astro** site (usually with **Starlight** for the docs chrome). Use the project's package manager; examples use pnpm.
+
+## What is on npm
+
+| Package | Role |
+|---|---|
+| `create-idocs` | `npm create idocs@latest`: scaffolds a new site. |
+| `@the-package-labs/idocs` | The CLI: `idocs check`, `list`, `schema`, `icons search`, `new`. |
+| `@the-package-labs/idocs-astro` | The Astro integration and the `<Diagram>` component. |
+| `@the-package-labs/idocs-react` | The interactive diagram component (a dependency of the integration). |
+| `@the-package-labs/idocs-core` | Schema, compiler and layout (a dependency of the others). |
+
+The source is `https://github.com/The-Package-Labs/idocs`. If an install fails with "not found", check `npm view @the-package-labs/idocs-core version`: it should print a version. A company registry mirror may simply not have the `@packagelab` scope yet.
+
+## Start a new site
+
+```sh
+npm create idocs@latest my-docs
+cd my-docs
+pnpm install
+pnpm dev                 # http://localhost:4321
+```
+
+This creates an Astro + Starlight project with an example diagram (`diagrams/shop`), three pages, a GitHub Pages workflow, and this skill. The folder must be empty or not exist. Edit `diagrams/shop/diagram.yaml` and the page reloads.
+
+## Add idocs to an existing Astro + Starlight site
+
+1. **Install.**
+   ```sh
+   pnpm add @the-package-labs/idocs-astro @the-package-labs/idocs-react @astrojs/react react react-dom
+   pnpm add -D @the-package-labs/idocs
+   ```
+   On pnpm 10 or later, allow the build scripts it asks about by adding to `pnpm-workspace.yaml`:
+   ```yaml
+   allowBuilds:
+     esbuild: true
+     sharp: true
+   ```
+2. **Register the integrations** in `astro.config.mjs`:
+   ```js
+   import react from '@astrojs/react'
+   import starlight from '@astrojs/starlight'
+   import idocs from '@the-package-labs/idocs-astro'
+   import { defineConfig } from 'astro/config'
+
+   export default defineConfig({
+     integrations: [
+       idocs(),                 // compiles diagrams/ at build time; the build fails on a broken diagram
+       react(),
+       starlight({
+         title: 'My docs',
+         // Widens the content column for diagrams and keeps prose at a readable width.
+         customCss: ['@the-package-labs/idocs-astro/starlight.css'],
+       }),
+     ],
+   })
+   ```
+   `idocs({ dir: 'my-diagrams' })` changes the folder (default `diagrams`).
+3. **Types.** In `src/env.d.ts` add `/// <reference types="@the-package-labs/idocs-astro/virtual" />`.
+4. **A first diagram.**
+   ```sh
+   pnpm idocs new shop
+   pnpm idocs schema        # editor autocomplete for diagram.yaml
+   pnpm idocs check
+   ```
+5. **A page** (`src/content/docs/shop.mdx`):
+   ```mdx
+   ---
+   title: Shop
+   tableOfContents: false
+   ---
+   import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
+
+   <Diagram name="shop" />
+   ```
+6. Add `"check": "idocs check"` to `package.json` scripts, and run it in CI.
+
+For an Astro site without Starlight, the same steps apply except for `customCss`; give the diagram a wide container.
+
+## Publish to GitHub Pages
+
+The template ships `.github/workflows/deploy.yml`. For an existing site, add a workflow that installs, runs `pnpm check`, builds with `SITE_URL=https://<owner>.github.io` and `BASE_PATH=/<repo>`, and deploys `dist/` with `actions/deploy-pages`. In `astro.config.mjs` use `site: process.env.SITE_URL, base: process.env.BASE_PATH`.
+
+The repository's **Settings → Pages → Source** must be set to **GitHub Actions** once. Until it is, the deploy step fails with a 404; the template's workflow detects that and skips the step with a notice.
+
+## Install this skill in another project
+
+```sh
+npx skills add The-Package-Labs/idocs --skill idocs          # this project
+npx skills add The-Package-Labs/idocs --skill idocs -g       # every project
+```
+
+Projects created with `create-idocs` already contain it in `.claude/skills/idocs`.

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

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+Run `idocs check --json` first. Each message has a file, line, column and often a hint.
+
+## Diagram errors
+
+| Message | Fix |
+|---|---|
+| `Edge from "x" is not a node` / `Edge to "x" ...` | A typo or an undeclared node. The hint names the nearest id. |
+| `"x" is not a node` (in a scenario) | Same, inside a step, `via`, `lanes` or a view's `include`. |
+| `No path from "a" to "b" in view "v"` | The step needs a route. Declare an edge between them (it can be `hidden: true`), or add `via: [...]` through nodes that are connected. |
+| `Node "x" is not in view "v"` | The scenario's view does not include `x`. Add it to `include`, or set the scenario's `view:`. |
+| `Unknown key "titel"` | A typo. The hint suggests the right key; the message lists allowed keys. |
+| `Not a recognised step` | Steps are `a -> b: label`, `at node: label`, or `par:` with a list. Check spacing and the arrow. |
+| `A step with at needs a label or a title` | `at x:` needs text: `at x: what happens`. |
+| `"x" is not a direct member of group "g"` | Entries in a group's `rows:` must be nodes or groups whose `in:` is that group. |
+| `Groups are nested in a cycle` | A group's `in:` chain loops back on itself. |
+| `Edge id "e" is used twice` | Give edges distinct ids or drop the ids. |
+| `Unknown edge kind "x"` | Use a built-in kind or define it under `edgeKinds:`. |
+| warning `Unknown icon "x"` | `idocs icons search x`, then use the suggested name. |
+| warning `Doc file "x" was not found` | A `doc:` path that does not exist. Paths are relative to the diagram folder. |
+| warning `... appears in the story but is in no lane` | A `lanes:` list that leaves out a node the scenario uses. Add it to a lane or ignore: it gets its own lane at the end. |
+| warning `Node "x" cites "src/y.ts", which does not exist` | A `refs:` path that moved. Update the diagram or the reference. |
+
+## YAML pitfalls
+
+- **Flow maps and commas.** In `{ label: a, b, kind: x }` the comma ends the value. Quote it: `{ label: "a, b", kind: x }`. Same for a colon followed by a space.
+- **Values starting with `{`, `[`, `*`, `&`, `!`, `%`, `@` or a backtick** need quotes.
+- **Ports and times** like `:8080` need quotes: `sub: ":8080"`.
+- **Indentation** is spaces only, two per level. Steps under `phases:` sit under that phase's `steps:`.
+- **Multi-line text** uses `|` and indentation:
+  ```yaml
+  detail: |
+    first line
+    second line
+  ```
+- **`Invalid input: expected string, received undefined`** at a path: a required field is missing there.
+
+## The site
+
+| Symptom | Check |
+|---|---|
+| `<Diagram name="x"> does not match a diagram` | The folder name differs. The error lists the available names. |
+| Build fails with `Diagram errors:` | Run `idocs check`; the build fails on any diagram error by design. |
+| The diagram shows "Loading diagram..." and never appears | A browser console error. Is `react()` from `@astrojs/react` in `astro.config.mjs`? |
+| Edits to a diagram do not show in dev | Save the file again; if the compiler itself changed (an idocs upgrade), restart the dev server. |
+| The page is narrow with a tiny diagram | The Starlight content column. Add `@the-package-labs/idocs-astro/starlight.css` to Starlight's `customCss`. |
+| Fonts differ from the screenshots | The templates use IBM Plex via `@fontsource/ibm-plex-sans` and `-mono`; add them or set `--idocs-sans` and `--idocs-mono`. |
+| Diagram looks blurry when zoomed | Use the current `@the-package-labs/idocs-react`; older builds kept the zoom layer on the GPU. |

package/template/.github/workflows/deploy.yml

@@ -0,0 +1,60 @@
+name: Deploy to GitHub Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      pages: ${{ steps.pages.outputs.enabled }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check --strict
+      - run: pnpm build
+        env:
+          # Project pages live under /<repo>/. Remove BASE_PATH if you use a custom domain.
+          SITE_URL: https://${{ github.repository_owner }}.github.io
+          BASE_PATH: /${{ github.event.repository.name }}
+      - id: pages
+        name: Is GitHub Pages enabled?
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh api "repos/${{ github.repository }}/pages" --silent 2>/dev/null; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice title=GitHub Pages is not enabled::Open Settings > Pages, set the source to 'GitHub Actions', then re-run this workflow. The site was built, but not deployed."
+          fi
+      - uses: actions/upload-pages-artifact@v3
+        if: steps.pages.outputs.enabled == 'true'
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    if: needs.build.outputs.pages == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/template/CLAUDE.md

@@ -0,0 +1,27 @@
+# My docs
+
+Documentation site built with [idocs](https://github.com/The-Package-Labs/idocs): Astro + Starlight pages with architecture diagrams that readers can click and play.
+
+## Commands
+
+```sh
+pnpm install
+pnpm dev                    # http://localhost:4321
+pnpm check [--json]         # validate every diagram (errors say file:line:col and suggest fixes)
+pnpm build                  # static site in dist/
+pnpm idocs new <name>       # new diagram folder
+pnpm idocs list --json      # what diagrams, views and scenarios exist
+pnpm idocs icons search <q> # find an icon name
+```
+
+## Where things are
+
+- `diagrams/<name>/diagram.yaml`: one diagram (nodes, groups, edges, views, scenarios)
+- `diagrams/<name>/nodes/<id>.md`: what a reader sees when they click that box
+- `diagrams/<name>/scenarios/<id>.yaml`: a long scenario in its own file
+- `src/content/docs/*.mdx`: the pages; embed a diagram with `<Diagram name="<name>" />`
+- `src/styles/custom.css`: theme tokens (`--idocs-*`)
+
+## Working on diagrams
+
+Use the `idocs` skill (`.claude/skills/idocs`). Read the code you are documenting, write the YAML, then **always** run `pnpm check` and look at the rendered page before you finish. Never invent services, ports or flows.

package/template/README.md

@@ -0,0 +1,30 @@
+# My docs
+
+Interactive architecture docs, built with [idocs](https://github.com/The-Package-Labs/idocs).
+
+```sh
+pnpm install
+pnpm dev          # http://localhost:4321
+```
+
+Diagrams live in `diagrams/`, pages in `src/content/docs/`. Start with `diagrams/shop/diagram.yaml`, change a label, and save: the page reloads.
+
+| | |
+|---|---|
+| `pnpm check` | validate diagrams |
+| `pnpm idocs new <name>` | add a diagram |
+| `pnpm build` | build the static site into `dist/` |
+
+## Publish
+
+Push to GitHub, open **Settings → Pages**, and choose **GitHub Actions** as the source. The workflow in `.github/workflows/deploy.yml` builds and publishes on every push to `main`.
+
+## Draw with an AI agent
+
+The `idocs` skill in `.claude/skills/` teaches Claude Code the diagram format. For other agents or other projects: `npx skills add The-Package-Labs/idocs --skill idocs`.
+
+## Update idocs
+
+```sh
+pnpm up "@the-package-labs/idocs-*" --latest
+```

package/template/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.astro
+.DS_Store
+*.log
+.env

package/template/_pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+# pnpm 10+ asks you to approve dependency build scripts. These two are safe and needed.
+allowBuilds:
+  esbuild: true
+  sharp: true

package/template/astro.config.mjs

@@ -0,0 +1,32 @@
+import react from '@astrojs/react'
+import starlight from '@astrojs/starlight'
+import idocs from '@the-package-labs/idocs-astro'
+import { defineConfig } from 'astro/config'
+
+// Publishing to GitHub Pages: the deploy workflow sets SITE_URL and BASE_PATH for you.
+export default defineConfig({
+  site: process.env.SITE_URL,
+  base: process.env.BASE_PATH,
+  integrations: [
+    idocs(),
+    react(),
+    starlight({
+      title: 'My docs',
+      description: 'How our system works, with diagrams you can play.',
+      customCss: [
+        '@fontsource/ibm-plex-sans/400.css',
+        '@fontsource/ibm-plex-sans/500.css',
+        '@fontsource/ibm-plex-sans/600.css',
+        '@fontsource/ibm-plex-mono/400.css',
+        '@fontsource/ibm-plex-mono/500.css',
+        '@the-package-labs/idocs-astro/starlight.css',
+        './src/styles/custom.css',
+      ],
+      sidebar: [
+        { label: 'Overview', slug: 'index' },
+        { label: 'How the shop works', slug: 'architecture' },
+        { label: 'Editing diagrams', slug: 'editing' },
+      ],
+    }),
+  ],
+})