diff --git a/.agents/skills/codebase-context/SKILL.md b/.agents/skills/codebase-context/SKILL.md index 4f24645b8..d7676ad92 100644 --- a/.agents/skills/codebase-context/SKILL.md +++ b/.agents/skills/codebase-context/SKILL.md @@ -37,4 +37,4 @@ Orient from the current checkout before editing. Treat package manifests, export - Cron jobs: `packages/cron-jobs/src/jobs/` - App routes: `apps/nextjs/src/app/[locale]/` -Invoke `documentation-sync` when hidden capabilities or information not evident to an advanced user change, or existing guidance becomes inaccurate; follow the Documentation Sync criteria in `AGENTS.md`. When exposing tRPC through MCP, invoke `mcp-integration`. +Invoke `documentation-sync` only when users need new or corrected information to set up, use, or troubleshoot Homarr; follow the Documentation Sync criteria in `AGENTS.md`. When exposing tRPC through MCP, invoke `mcp-integration`. diff --git a/.agents/skills/documentation-sync/SKILL.md b/.agents/skills/documentation-sync/SKILL.md index 0f06a2f15..ecf88992c 100644 --- a/.agents/skills/documentation-sync/SKILL.md +++ b/.agents/skills/documentation-sync/SKILL.md @@ -1,11 +1,11 @@ --- name: documentation-sync -description: Write concise Homarr docs only when changed behavior is not clear to a smart, advanced user from the UI or generated schema. Skip routine, obvious, or self-explanatory changes. +description: Write Homarr docs only when users need information to set up, use, or troubleshoot the app. Skip routine, obvious, or self-explanatory changes. --- # Documentation Sync -Apply the audience and scope rules in `AGENTS.md` first. A code, UI, or API change alone does not warrant documentation. Add a passage only when a smart, advanced user cannot infer the behavior from the interface or generated schema. +Apply the audience and scope rules in `AGENTS.md` first. Documentation exists only for information users need to set up, use, or troubleshoot Homarr. A code, UI, or API change alone does not warrant documentation; if a user does not need to know it, do not add it. For hidden capabilities such as the advanced widget feature, explain discovery, activation, and non-obvious behavior. For visible standard controls such as Delete, omit narration of what the label already conveys. Use the shortest explanation that preserves necessary technical detail; remove redundant prose in the passage being edited. @@ -50,7 +50,7 @@ For a widget: ## Completion criteria -1. Every passage adds information an advanced user cannot reasonably infer from the interface. Remove obvious, repetitive, or unnecessary prose. +1. Every passage adds information a user needs and cannot reasonably infer from the interface. Remove obvious, repetitive, or unnecessary prose. 2. Keep names, defaults, paths, screenshots, links, and prerequisites consistent with code. 3. Update every affected page and remove superseded guidance. 4. Run the narrowest useful docs validation. Use `pnpm turbo build --filter=@homarr/docs` when links, MDX, generated definitions, or navigation can fail; otherwise run the docs package formatter on touched files. diff --git a/.agents/skills/documentation-sync/agents/openai.yaml b/.agents/skills/documentation-sync/agents/openai.yaml index 9c9b77cc5..4cb45e135 100644 --- a/.agents/skills/documentation-sync/agents/openai.yaml +++ b/.agents/skills/documentation-sync/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Homarr Documentation Sync" - short_description: "Keep user-facing docs aligned with code" - default_prompt: "Use $documentation-sync to map this Homarr code change to the required documentation updates." + short_description: "Document only what users need to know" + default_prompt: "Use $documentation-sync only when users need new or corrected information to set up, use, or troubleshoot Homarr." diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 236fd1787..dbaab3791 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,7 +10,7 @@ - [ ] Pull request targets the intended base branch (`dev` by default; `release/v2` for v2 release work) - [ ] Commits follow the [conventional commits guideline](https://www.conventionalcommits.org/en/v1.0.0/) - [ ] No shorthand variable names are used (for example, `x`, `y`, `i`, or abbreviations) -- [ ] User-facing changes include matching documentation updates under `apps/docs` +- [ ] Documentation under `apps/docs` is updated only when users need new or corrected information to use the app - [ ] When using AI, no temporary files are checked in and the code style follows the rest of the project **When contributing a new integration or widget:** diff --git a/AGENTS.md b/AGENTS.md index 48b2acadd..aa3b9efa8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,11 +57,11 @@ homarr/ ## Documentation -Add or update docs only when a smart, advanced user cannot infer the changed behavior from the UI or generated API schema. Document hidden capabilities, surprising behavior, non-obvious prerequisites or constraints, configuration contracts, and migrations. A code or API change alone is not a reason to add docs. +Add documentation only when users need the information to set up, use, or troubleshoot Homarr and cannot reasonably discover it from the UI or generated API schema. If a user does not need to know it, do not document it. A code, UI, or API change alone is never a reason to add docs. -Keep warranted documentation concise. Omit UI walkthroughs, visible control descriptions, and details already clear from the interface or schema. +Keep warranted documentation concise. Omit UI walkthroughs, visible control descriptions, internal implementation details, and anything already clear from the interface or schema. -Only after this reader-value test passes, use these locations: +Only after this user-need test passes, use these locations: - New integration → `apps/docs/docs/integrations//index.mdx` + `index.ts` - New widget → `apps/docs/docs/widgets//index.mdx` + `index.ts` @@ -97,7 +97,7 @@ Only after this reader-value test passes, use these locations: ## Testing -Add tests only when requested. Favor assertions that would fail for a plausible regression in user-visible behavior or a security boundary; avoid checks that repeat implementation details or duplicate stronger coverage. For focused changes, run only the relevant existing or newly requested checks when validation is needed. Do not run broad test, Docker, or E2E suites by default. +Add tests only when requested, and only when the test is extremely relevant and will plausibly prevent a future regression in user-visible behavior or a security boundary. Do not add tests that restate implementation details or duplicate stronger coverage. For focused changes, run only the relevant existing or newly requested checks when validation is needed. Do not run broad test, Docker, or E2E suites by default. ## MCP servers @@ -108,6 +108,6 @@ Add tests only when requested. Favor assertions that would fail for a plausible Portable skills live in `.agents/skills/`. Read the relevant `SKILL.md` before working in that domain; detailed references are loaded only when needed. Claude-compatible discovery is provided through `.claude/skills`. - `codebase-context` — architecture, package boundaries, and shared utilities -- `documentation-sync` — documentation for changes users need explained +- `documentation-sync` — user-critical documentation only - `mcp-integration` — safe tRPC-to-MCP exposure - `homarr-custom-widget` — safe Custom JSX v2 authoring