Make write-docs skill trigger proactively and track menu entries (#2747)

.agents/skills/write-docs/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: write-docs
-description: Write or update Tabler documentation pages in simple English using the current docs schema. Use when the user asks to create docs, edit docs, add new feature docs to an existing page, or standardize docs structure across any docs category.
-disable-model-invocation: true
+description: Write, update, or suggest Tabler documentation pages in simple English using the current docs schema. Use whenever the user asks to create docs, edit docs, add new feature docs to an existing page, or standardize docs structure across any docs category. Also consult this skill proactively — without being asked — whenever a new visual UI component (shared/ui/*.astro), plugin, or other user-facing feature has just been added or changed and has no matching, up-to-date page under docs/pages/**, since undocumented components are easy to forget about.
 ---
 
 # Write Tabler Docs
 
-Write docs directly in files (do not stop at draft mode) and follow the current Tabler documentation schema.
+Follow the current Tabler documentation schema. How far to go depends on how the skill was triggered — see section 1.
 
 ## 1. Scope and behavior
 
@@ -15,6 +14,11 @@ Write docs directly in files (do not stop at draft mode) and follow the current
 - Create new pages when needed.
 - Use simple English in all prose.
 
+### Direct request vs. proactive suggestion
+
+- If the user explicitly asked for docs (e.g. "document this", "write docs for X", "update the badge page"), write directly in the files — do not stop at draft mode.
+- If this skill triggered on its own because something was built or changed without matching docs, don't start editing files unprompted. Point out what's missing in one or two sentences (which component/plugin, which page it would live under) and ask whether to write it. Proceed to write directly, per the rule above, only once the user says go.
+
 ## 2. Required language style (simple English)
 
 - Use short sentences and common words.
@@ -79,29 +83,51 @@ import Example from '@components/Example.astro';
 - For icons and other shared components inside examples, import them from `@ui/` (for example `<Icon name="plus" />`).
 - Raw HTML in the `Example` slot is reserialized by MDX — keep markup lines attached to tags to avoid stray `<p>` wrapping.
 
-## 6. Workflow for each request
+## 6. Analyzing the component or plugin source
 
-1. Identify target file(s) in `docs/pages/**`.
+Prose and example markup are only as accurate as their source. Before writing examples, ground them in the actual implementation rather than in guesses or in what a similar-looking page happens to show — nearby `.mdx` pages are a good style reference but can drift out of sync with the code.
+
+- **UI components** live at `shared/ui/<ComponentName>.astro`. Read its `interface Props` block: each field (and its JSDoc comment, when present) is the authoritative list of supported options, defaults, and edge cases — for example `shared/ui/Badge.astro` documents `scale`, `light`, `icon`, and `personId` this way.
+- **Plugins and utilities** are often CSS-class-driven rather than a single Astro component. Check `core/scss/**/_<name>.scss` (or `core/scss/tabler-<name>.scss`) for the class variants that actually exist, and `shared/data/<name>.json` when the plugin is data-driven (e.g. `flags`, `payments`, `social-icons`).
+- **Real usage** in `preview/pages/**` renders the finished HTML and often exercises more combinations in practice than the docs page does — a useful cross-check for realistic examples.
+- Turn what you find into `<Example>` blocks that reflect real, valid prop/class combinations rather than invented markup.
+
+## 7. Registering new pages in the docs menu
+
+`docs/pages/**` is not scanned automatically to build navigation — the sidebar tree is frozen in `shared/data/docs.json` (see the comment in `docs/components/DocsMenu.astro`). A new leaf page with no entry there exists but is unreachable from the docs site.
+
+- Only touch `docs.json` for genuinely **new** pages. Editing an existing page needs no menu change.
+- Find the matching section in the `menu` array by directory: `docs/pages/ui/components/*` → the `"Components"` entry under `"Tabler UI"`, `docs/pages/ui/plugins/*` → `"Plugins"`, `docs/pages/icons/libraries/*` → `"Libraries"` under `"Tabler Icons"`, and so on — the section `title`/`url` pairs mirror the `docs/pages/ui/*` and `docs/pages/icons/*` subdirectory names.
+- Add `{ "title": "<Title Case name>", "url": "/<matching>/<slug>/" }` to that section's `children`, in the same alphabetical position its neighbors already follow.
+- The `title` and `url` must match the new page's frontmatter `title` and its file path exactly, or the sidebar entry will point at the wrong place.
+
+## 8. Workflow for each request
+
+1. Identify target file(s) in `docs/pages/**` (or determine none exist yet — see section 7).
 2. Read the target page and 2-3 nearby pages in the same category to match tone and conventions.
-3. Apply the schema from section 4.
-4. Write/update the page directly in file(s).
-5. Keep only required frontmatter by default.
-6. Ensure prose is in simple English.
-7. Verify heading hierarchy (`##` then `###`) and snippet validity.
+3. Read the underlying component/plugin source per section 6 so examples are accurate, not guessed.
+4. Apply the schema from section 4.
+5. Write/update the page directly in file(s).
+6. If the page is new, add its entry to `shared/data/docs.json` per section 7.
+7. Keep only required frontmatter by default.
+8. Ensure prose is in simple English.
+9. Verify heading hierarchy (`##` then `###`) and snippet validity.
 
-## 7. Rules while updating existing docs
+## 9. Rules while updating existing docs
 
 - Preserve valid existing content that is still correct.
 - Add new functionality docs as focused new subsection(s), usually under `Variants`, `Usage`, or `Examples`.
 - Remove or rewrite only conflicting or outdated text.
 - Keep naming and terms consistent across the page.
 
-## 8. Quality checklist before finishing
+## 10. Quality checklist before finishing
 
 - [ ] Uses simple English.
+- [ ] Examples reflect the real Props/classes found in the source (section 6), not guesses.
 - [ ] Frontmatter uses static YAML.
 - [ ] Default frontmatter contains only `title`, `summary`, `description`, `layout` (unless user requested extra keys).
 - [ ] Follows schema and heading hierarchy.
 - [ ] Examples use the `Example` component pattern where applicable.
 - [ ] Accessibility section exists for interactive UI docs.
+- [ ] New pages have a matching entry in `shared/data/docs.json` (section 7); edits to existing pages don't touch it.
 - [ ] No mention of changeset reminders unless user asks.