| name | solidinvoice-feature-docs |
| description | Use when the user asks to create, write, or add end-user documentation for a SolidInvoice feature, or to "document the changes in the current branch". Triggers on phrases like "document this feature", "write docs for X", "add a docs page", "document the client creation flow", "create user documentation", or any request to produce Docusaurus-rendered user-facing documentation under the SolidInvoice docs/ directory. Also use when working in the SolidInvoice repo and the user asks for documentation help, even without explicitly mentioning Docusaurus or the docs folder. Do not use this skill for developer/contributor docs, README updates, or API reference — only for end-user documentation in docs/. |
SolidInvoice feature documentation
Produce a single, focused, end-user documentation page for one SolidInvoice feature, fitted to the project's Docusaurus site.
Non-negotiables
- Accuracy first. Never invent UI labels, fields, settings, command flags, or behavior. If you cannot verify it from the codebase or a screenshot, ask the user — do not guess.
- One feature per run. Resist the urge to document related features. Cross-link instead.
- Concise, not skeletal. Cover everything a user needs to use the feature; cut anything obvious, decorative, or already covered elsewhere.
- Read
docs/CLAUDE.md before writing. It defines the Docusaurus conventions for this repo (frontmatter, _category_.json, admonitions, image paths, sidebar autogeneration). Treat it as authoritative — do not invent alternatives.
Site facts you should always assume
These are stable for this repo; you don't need to re-research them every run:
- Site is Docusaurus. Content lives under
docs/docs/. Static assets live under docs/static/img/.
routeBasePath: '/' — pages are served at the site root, no /docs/ URL prefix.- Sidebar is autogenerated from the folder tree. There is no
SUMMARY.md or manual sidebar list — placement = folder choice + sidebar_position in frontmatter + _category_.json for sections.
onBrokenLinks: 'throw' and onBrokenMarkdownLinks: 'throw' — broken links fail the build. Verify every link.- Build command:
bun run build. Dev server: bun run start.
Workflow
1. Determine scope
Two entry modes:
A. Explicit feature (e.g. "document the client create process"):
Restate the feature in one sentence and confirm scope before researching. Example: "I'll document creating a client through the UI — the form, required fields, and what happens on save. Want me to also include editing/archiving, or keep this to creation only?"
B. Current branch ("document the changes in this branch"):
Run git diff <main-branch>...HEAD --stat and git log <main-branch>..HEAD --oneline to map what changed. Read the relevant changed files to infer the user-visible feature. Then propose to the user, in 2-3 sentences: what feature you think the docs should cover, what scope, and which pages it affects (new page vs. update to existing). Wait for confirmation before continuing.
2. Research the feature
Build an accurate model of the feature before writing. Read in this order:
- Code — find the Action class(es), Form types, entities, Twig templates, routes, and any Manager classes. The bundle structure in the project's root
CLAUDE.md tells you where to look.
- Running app (only when UI is involved) — ask the user for the local URL and any login/state required, then use
chrome-devtools-mcp (preferred over claude-in-chrome for clean screenshots) to inspect the page. Verify field labels, button text, error messages, and flow against the code.
- User clarification — for anything ambiguous (intended use, edge case, planned vs. shipped behavior), ask. Do not paper over uncertainty.
While researching, capture:
- The exact UI labels users see (don't paraphrase — copy them).
- Required vs. optional fields.
- Gotchas, prerequisites, permissions, or settings that affect the feature.
- Related features already documented (candidates for cross-links). Skim 1-2 existing pages in the same section so the new page reads consistently.
3. Plan the page
Before writing prose, propose to the user:
- File path under
docs/docs/. Use existing section folders (e.g. managing-clients/, companies/, installation-guide/, integrations/); only create a new section if no existing one fits. Standalone top-level pages are also valid for cross-cutting topics (see cron-job-setup.md).
- Sidebar placement — proposed
sidebar_position and, if creating a new section, the _category_.json you'd add. Note any sibling pages whose sidebar_position would need bumping. Wait for confirmation; do not auto-place.
- Page outline — title and
## headings in order. Keep it lean — typically 3-6 headings.
- Screenshots needed — list the screenshots with proposed paths under
static/img/<section>/. Ask whether you should capture them via Chrome DevTools (provide the URL + any login state) or whether the user will supply them.
Wait for confirmation or adjustment before drafting.
4. Screenshots
When capturing yourself with chrome-devtools-mcp:
-
Use a clean test instance — avoid real customer data in frame.
-
Focus on the relevant area; full-window screenshots with browser chrome are usually too noisy.
-
Save into docs/static/img/<section>/ with descriptive lowercase-hyphenated filenames (e.g. create-client-form.png).
-
Reference using root-absolute markdown image syntax (the repo convention — do not invent alternatives):
-
Always supply meaningful alt text — broken/missing images surface it, and screen readers depend on it.
When asking the user to supply a screenshot, give them: the exact URL/page, what should be visible, the filename to save as, and the destination path. Wait for confirmation before referencing it in the page.
5. Write the page
Follow the conventions in docs/CLAUDE.md (frontmatter, second person, task-oriented title, admonitions, code-block language tags). A typical shape:
---
title: Creating a client
description: Add a new client to SolidInvoice.
sidebar_position: 1
---
# Creating a client
Add a new client to your SolidInvoice account so you can issue them quotes and invoices.
## Open the create form
From the sidebar, click `Clients`, then click the `+ Add Client` button.
## Fill in the client details
...
:::info
Currency is set per client and is used for all their quotes and invoices.
:::
## Save
...
## Related
- [Adding contacts to a client](./contacts.md)
- [Creating an invoice](../invoices/creating-an-invoice.md)
Rules of thumb:
- Frontmatter is required. Every page starts with
title, description, sidebar_position. The # H1 in the body should match the title.
- Admonitions (
:::info, :::tip, :::warning, :::danger, :::note) for gotchas, prerequisites, and "good to know" notes. Don't bold-warn inline.
- Code blocks with language tags for commands, config, or env vars (
bash, php, yaml, json, nginx, apacheconf, docker, ini are configured for highlighting). Use title="filename" when it adds context.
- Tabs — use Docusaurus
<Tabs> (in an .mdx file) for genuinely platform-specific instructions like OS-by-OS or webserver-by-webserver. Don't reach for tabs when a single section + note would do.
- Cross-links instead of re-explaining. A 1-2 sentence pointer + relative
.md link beats a duplicated section.
- Don't pad. No "Introduction", no "Conclusion", no restating the title in the first sentence.
- Don't reference 2.4.x unless that's deliberately the subject — current dev branch is
3.0.x.
6. Wire up navigation
The sidebar is autogenerated, so navigation hooks are:
- The page's
sidebar_position in frontmatter.
- A
_category_.json in the section folder (only if creating a new section). Show the user the proposed JSON before saving — copy from a similar existing section.
- Sibling pages whose
sidebar_position you bumped, if any.
Show the user a summary of what got changed (file added, frontmatter positions touched, _category_.json added) before claiming done.
7. Verify before claiming done
Walk this checklist explicitly — don't skim:
- Every claim is backed by code or a screenshot — no invented field names, labels, or behavior.
- Frontmatter is present and complete (
title, description, sidebar_position).
- Image paths are root-absolute (
/img/...) and the files exist on disk under docs/static/img/.
- Internal links are relative
.md paths and resolve.
- No content duplicated from other pages — pointers instead.
- Admonitions used (not blockquotes), markdown image syntax used.
- No
2.4.x links unless intentional.
- Run
bun run build in the docs/ directory. The build catches broken links, broken markdown links, and frontmatter errors. Fix anything it flags before declaring done.
Report what you did in 2-3 sentences: file created, sidebar position, screenshots captured or requested, build status. Don't summarize the page contents — the user will read it.
Common failure modes
- Inventing UI labels. If you didn't see "Add Client" in the code or a screenshot, don't write it — ask.
- Documenting more than asked. "While I'm here, let me also cover editing" → no. One feature.
- Padding. "In this guide, we will explore..." → cut. Open with the task.
- Duplicating settings docs. If a feature depends on a setting documented elsewhere, link to that page; don't re-explain it.
- Skipping
bun run build. Strict link checking means a doc that "looks fine" can still break the build.
- Forgetting frontmatter. Without
title/sidebar_position, the page either fails to build or shows up in the wrong place.
- Wrong image path. Images live in
docs/static/img/..., but pages reference them as /img/... (root-absolute). Don't use ../ paths.
- Mixing developer-doc style with end-user style. Audience is freelancers and small business owners. No internal class names, no architecture, no API jargon unless the feature itself is the API.
