document360-writer 0.1.0

package/skills/audit-docs/SKILL.md

@@ -0,0 +1,48 @@
+# Skill: audit-docs
+
+**Activate when** the user runs `/audit` or asks "what's stale", "what's missing", "where are the gaps".
+
+**Goal:** produce a table of articles that need attention, with a concrete reason per row.
+
+## What to do
+
+1. Read `.d360-writer.json` for the `captureDir`, `outputDir`, and `authoritativeSourceFiles` list.
+2. Read every existing article under the docs root (typically `user-docs/`).
+3. Read recent git history: `git log --since="30 days ago" --name-only --pretty=format:"%h %s"`. If `d360-category-map.json` exists, prefer commits since its mtime.
+4. For each commit, identify which articles describe the affected code paths. Cross-reference using the authoritative source files list and the article-to-code links you can infer.
+5. For each existing article, check whether its claims still match the source code. Look for: renamed components, changed UI strings, removed features, added features.
+
+## Output format
+
+A single markdown table. Nothing else.
+
+| Article path | Action | Reason | Scope |
+|---|---|---|---|
+| `03-foo/02-bar.md` | update | commit `abc123` renamed the "Bar" dialog to "Settings" | small |
+| `04-baz/06-new-feature.md` | create | commit `def456` shipped a feature with no doc | full article |
+| `02-spec/04-old-thing.md` | delete | commit `ghi789` removed the feature; no replacement | full deletion |
+
+## Action values
+
+- `create` — article doesn't exist, but the feature it would describe is real and shipped.
+- `update` — article exists but disagrees with current code.
+- `delete` — article describes a removed feature.
+- `keep` — explicitly noted as up-to-date and intentional. Don't include `keep` rows unless the user asked for them.
+
+## Scope values
+
+- `small` — a UI string, a step renumbering, a one-line clarification.
+- `medium` — a section rewrite or a new screenshot.
+- `full article` — net-new article or near-complete rewrite.
+- `full deletion` — remove from disk and from D360.
+
+## Rules
+
+- Quote the commit hash for every claim. No vague "the code changed."
+- Do not start fixing anything. The audit is the deliverable.
+- If the codebase has zero existing articles, redirect the user to `propose-structure` instead and emit nothing.
+- If the audit has zero rows, say so plainly: "All articles are in sync with the codebase as of `<HEAD-sha>`."
+
+End your output with:
+
+> Want me to start working through these? Reply with `yes` or strike rows you want to defer.

package/skills/emit-screenshot-spec/SKILL.md

@@ -0,0 +1,82 @@
+# Skill: emit-screenshot-spec
+
+**Activate when** you've just emitted a `<!-- SCREENSHOT ... -->` placeholder block in an article, OR the user runs `/screenshot <id>`.
+
+**Goal:** generate a Playwright `.spec.ts` file in the configured `captureDir` that the `document360-capture` (alias `d360-capture`) CLI can execute end-to-end against the user's running product.
+
+## Where the spec lands
+
+`<captureDir>/<placeholder.id>.spec.ts` — read `captureDir` from `.d360-writer.json` (default: `user-docs/_capture`).
+
+## Spec template
+
+```typescript
+import { test } from '@playwright/test';
+import { waitPastLogin, dumpAnnotations, type Placeholder } from 'document360-capture/helpers';
+
+const PLACEHOLDER: Placeholder = {
+  id: '<placeholder.id>',
+  saveTo: '<placeholder.save-to>',
+  highlight: [
+    // one stable selector per placeholder.highlight entry
+  ],
+  annotations: [
+    // { target: '<stable selector>', label: '1', text: '<short text>' }
+  ],
+  redact: [
+    // one stable selector per placeholder.redact entry
+  ],
+};
+
+test('<placeholder.id>', async ({ page }) => {
+  await page.goto(process.env.CAPTURE_START_URL!);
+  await waitPastLogin(page, new RegExp(process.env.CAPTURE_AUTH_BOUNDARY!));
+
+  // Translated from placeholder.steps — one Playwright action per step.
+  // Use STABLE selectors only.
+  // ...
+
+  await page.waitForSelector('<target state selector>', { state: 'visible' });
+  await page.waitForTimeout(500);
+
+  await page.locator('<capture target selector>').screenshot({ path: PLACEHOLDER.saveTo });
+  await dumpAnnotations(page, PLACEHOLDER);
+});
+```
+
+## Selector quality rule (non-negotiable)
+
+Use stable selectors in this priority order:
+
+1. `[data-testid="..."]` — best.
+2. `[aria-label="..."]` — good.
+3. `<role>:has-text("...")` / `role=button[name="..."]` — acceptable when unique.
+4. Visible text (`text=...`, `:has-text(...)`) — acceptable for top-level nav and unique buttons.
+
+**Never** use CSS classes, `nth-child`, deep DOM paths, or auto-generated IDs (`#mui-12345`).
+
+## TODO escape hatch (when stable selectors don't exist)
+
+If a required interaction has no stable selector, do NOT write a fragile one. Instead:
+
+1. Use `test.skip(...)` instead of `test(...)`.
+2. Add a top-of-file comment: `// TODO: add data-testid="<suggested-name>" to <ComponentName> at <src/.../File.tsx>. Capture spec disabled until then.`
+3. Tell the user which file + component to fix, plus the `data-testid` value you'd recommend.
+
+The manual intern path in the placeholder still works — only the automated capture is blocked.
+
+## Capture region (the placeholder's `capture` field)
+
+| `capture` value | Spec uses |
+|---|---|
+| `full-page` | `await page.screenshot({ path, fullPage: true })` |
+| `main-panel` | a stable container selector (read it from the project's main layout source) |
+| `modal-only` | `page.locator('[role="dialog"]').first().screenshot(...)` |
+| `panel-left` / `panel-right` | the project's named-panel selector |
+| `sidebar` | the project's sidebar selector |
+
+## After writing the spec
+
+- Report the spec's path.
+- If you used the TODO escape hatch, surface the blocking selectors so the dev can fix them in one pass.
+- Remind the user: `d360-capture auth --env <env>` once per machine, then `d360-capture capture <id>` to actually take the screenshot.

package/skills/gather-context-from-mcp/SKILL.md

@@ -0,0 +1,29 @@
+# Skill: gather-context-from-mcp
+
+**Activate when** the user asks you to write an article and they have connected MCP servers beyond Document360 — Notion, GitHub, Sentry, Slack, etc.
+
+**Goal:** enrich the article's source material with external context that lives outside the codebase.
+
+## What to do
+
+1. Inspect the connected MCP servers (the SDK exposes them — query tool names that match `mcp__<server>__*`).
+2. For each server, identify if it has relevant material:
+   - **Notion**: design docs, RFCs, retrospectives that explain why a feature exists.
+   - **GitHub**: PR descriptions, issue threads, commit messages with deeper context than the diff alone.
+   - **Sentry / observability**: real error signatures that justify a troubleshooting section.
+   - **Slack** (if connected): public-channel decisions or recent customer support patterns.
+3. Pull the minimum needed to ground specific claims. Don't dump entire docs.
+4. Cite the source. Every claim you draw from an external source goes into the article's `## Tips & notes` or `## Related articles` section with a link or reference.
+
+## When you should NOT activate
+
+- If the user hasn't connected any MCP servers beyond Document360. The source repo is enough.
+- If the user explicitly says "stay close to the code".
+- For short reference articles (CLI commands, config keys) where external context would just add noise.
+
+## Rules
+
+- Never paste raw MCP responses into the article. Distill into the article's voice.
+- Never include private identifiers (email addresses, internal URLs, customer names) unless they're meant to be public.
+- If an MCP server returns no relevant results, silently skip it and continue with the code-only sourcing.
+- Cap each external query at one round-trip per source per article — don't keep digging.

package/skills/propose-structure/SKILL.md

@@ -0,0 +1,51 @@
+# Skill: propose-structure
+
+**Activate when** the user has approved the codebase analysis and asks to "propose a structure", "outline the docs", or "what folders / articles should we have".
+
+**Goal:** produce a concrete documentation folder structure plus a flat list of proposed articles, ready for the user to approve before generation.
+
+## Folder structure rules
+
+- Numbered prefix per category: `01-getting-started`, `02-<primary-surface>`, etc.
+- Lowercase, kebab-case.
+- The first category is always `01-getting-started`. The last is always `99-troubleshooting-and-faq` (use `09-` or higher if you have fewer than 10 categories).
+- Between 4 and 12 categories. If you can't justify 4, the repo isn't ready for a structured docs site; recommend a single README instead.
+- Categories should map to the product's user-visible surfaces, not its internal code structure.
+
+## Article list rules
+
+- 2–8 articles per category.
+- Numbered prefix per article within a category: `01-what-is-x.md`, `02-install.md`, etc.
+- Each article entry includes: the path, a one-sentence purpose, and the source files the article would draw from.
+
+## Output format
+
+Use a markdown tree for the folder layout. Use a table for the article list:
+
+```
+user-docs/
+├── 01-getting-started/
+├── 02-<surface-a>/
+├── 03-<surface-b>/
+├── ...
+└── 99-troubleshooting-and-faq/
+```
+
+| Path | Purpose | Source files |
+|---|---|---|
+| `01-getting-started/01-what-is-<product>.md` | Define what the product is for end users | `README.md`, `src/pages/...` |
+| ... | ... | ... |
+
+## What you do NOT do
+
+- Do not start writing articles. That's `write-article`.
+- Do not create the folders yet — wait for the user to approve.
+- Do not invent features that aren't in the code.
+
+End your output with:
+
+> Want me to proceed with article generation? Reply with `yes`, or strike any rows you don't want.
+
+## After approval
+
+Once the user approves, create the empty folders (don't write file contents) and a single `AGENT-PLAN.md` at the repo's docs root that pins the approved table. The user can edit it; subsequent `write-article` invocations should respect it.

package/skills/publish-to-d360/SKILL.md

@@ -0,0 +1,39 @@
+# Skill: publish-to-d360
+
+**Activate when** the user runs `/publish <path>` or explicitly asks to publish one or more articles to Document360.
+
+**Goal:** dual-write each approved article — keep the source markdown in git, push the publish-form markdown to Document360 as a draft via the Document360 MCP server.
+
+## Preconditions
+
+- A Document360 MCP server must be registered. Check `/mcp list` mentally — the user's `~/.document360-writer/mcp.json` must contain an entry. If not, stop and tell the user to run `/mcp add document360 http <your-d360-mcp-url>`.
+- `.d360-writer.json` must have `d360.projectId` and `d360.projectVersionId` populated. If not, ask the user to run `/init` first or set them manually.
+- `<repo>/d360-category-map.json` is the source of truth for article IDs. Create it as `{ "projectId": "...", "projectVersionId": "...", "categories": {}, "articles": {} }` if missing.
+
+## Per-article steps
+
+1. Read the local `.md` file.
+2. Compute the publish form:
+   - Strip the H1 line.
+   - Strip every `<!-- SCREENSHOT ... -->` block. Keep the visible `[Screenshot: ...]` line.
+   - Convert relative `[link](../foo/bar.md)` to plain text like `See "foo" → "bar"`.
+3. Look up the article path in `d360-category-map.json` `articles` table.
+4. If found, call the D360 MCP `update-article` tool with `articleId`, `title` (from the H1 you stripped), `content` (the publish form), `contentType: 0`.
+5. If not found, call `create-article` with `categoryId` (resolve from the path's parent folder via `categories` table), `title`, `content`, `contentType: 0`. Capture the returned `articleId` and write it back into `d360-category-map.json`.
+6. Never overwrite a published article without confirming with the user.
+
+## After all articles
+
+Report:
+- Articles created: count + paths + new D360 article IDs.
+- Articles updated: count + paths + existing IDs.
+- Any failures + reason.
+- A reminder: **all writes are DRAFTS. Publish manually in the Document360 portal** at the configured `helpCenterBaseUrl`.
+
+## Rules
+
+- Never commit. The user handles git.
+- Never publish past draft. The user reviews and publishes in D360.
+- Never fabricate D360 IDs. If a UUID is missing, ask.
+- If a `create-article` call fails because the category doesn't exist in D360, ask the user whether to create it via `create-category` first.
+- Always update `d360-category-map.json` with new IDs in the same turn as the create.

package/skills/write-article/SKILL.md

@@ -0,0 +1,93 @@
+# Skill: write-article
+
+**Activate when** the user asks to write, draft, or generate a specific article — by topic name, by file path, or by reference to the approved plan.
+
+**Goal:** produce one publishable article that follows the system-prompt article structure exactly, grounded in the actual source code, and with screenshot placeholders where the user benefits from seeing the UI.
+
+## Before writing — gather
+
+1. Read the source files relevant to this article. Don't skip this. The whole point of this tool is that articles are grounded in code.
+2. Read `AGENT-PLAN.md` if present, to confirm the article's purpose matches the approved plan.
+3. Read 1–2 existing articles in the same category, if any, to match voice and structure.
+4. If `gather-context-from-mcp` is appropriate (the user has connected Notion / GitHub / etc. and the article would benefit from external context), invoke it.
+
+## Article skeleton (system-prompt-mandated)
+
+```
+# <Article title>
+
+<one-paragraph intro>
+
+## Prerequisites
+- <role/permissions, if any>
+- <required state>
+
+## Steps
+1. ...
+2. ...
+
+## Tips & notes
+- ...
+
+## Related articles
+- ...
+```
+
+## Screenshot placeholders
+
+When the article describes a UI flow that benefits from a visual, embed one or more screenshot placeholders. Each placeholder is two parts:
+
+1. An HTML comment block with capture instructions (stripped before D360 publish).
+2. A visible `[Screenshot: ...]` line (kept in both local and D360).
+
+Example:
+
+```markdown
+<!-- SCREENSHOT
+id: <kebab-case-stable-id>
+title: "<short title>"
+page-url: <relative path or URL>
+prerequisites:
+  - <plain-English state setup>
+steps:
+  1. <numbered actions with EXACT button labels>
+capture: <full-page | main-panel | modal-only | panel-left | panel-right | sidebar>
+device: desktop
+viewport: 1440x900
+highlight:
+  - <thing to draw attention to>
+annotations:
+  - <numbered callouts with short text>
+redact:
+  - <regions to hide (emails, real tokens, etc.)>
+save-to: user-docs/_screenshots/<id>.raw.png
+auto-capture-script: user-docs/_capture/<id>.spec.ts
+notes:
+  - <edge cases>
+-->
+[Screenshot: <short reader-facing description>]
+> 🤖 Auto-capture: `d360-capture capture <id>`
+> Sign in to Chromium when prompted; the script does the rest.
+```
+
+Every field must be filled. If a field doesn't apply, write "none" or "n/a" — never omit.
+
+**The `prerequisites` and `steps` fields must be detailed enough for a junior intern to capture the screenshot without further instruction.** If you can't write them that clearly, you don't understand the screen well enough — read more source code.
+
+For every screenshot placeholder you generate, also invoke `emit-screenshot-spec` so the matching `.spec.ts` lands in `<captureDir>/<id>.spec.ts`.
+
+## Writing rules (re-emphasis from system prompt)
+
+- Second person, imperative. No marketing language. No "simply", "just", "easily".
+- Quote exact UI strings. Read the React/HTML/etc. source.
+- State role-gating in **Prerequisites**, not in Steps.
+- Markdown only. One H1.
+
+## Output
+
+Write the article directly to its file path. Do not paste the markdown into the chat; the user wants the file on disk so they can review and iterate.
+
+After writing, report:
+- File path
+- Number of screenshot placeholders emitted (and a note that matching `.spec.ts` files were generated)
+- Any source files you couldn't find — the user may need to clarify