# Solidinvoice Feature Docs > 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/. - Skill: `tomevault-io/solidinvoice-feature-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/solidinvoice-feature-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/solidinvoice-feature-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/solidinvoice-feature-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 ...HEAD --stat` and `git log ..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: 1. **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. 2. **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. 3. **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/
/`. 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/
/` 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): ```markdown ![The client create form](/img/managing-clients/create-client-form.png) ``` - 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: ````markdown --- 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. ![The Clients list with the Add Client button](/img/managing-clients/clients-add-button.png) ## 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 `` (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. --- > Source: [SolidInvoice/SolidInvoice](https://github.com/SolidInvoice/SolidInvoice) — distributed by [TomeVault](https://tomevault.io).