docs(agents): define where a new document belongs (#3777)

## What this PR does

`docs/` had collected component guides that belong on the website,
standalone oidc, gpu and vm networking documents written inside the
feature PRs that added the code and never routed anywhere a user looks.
Nothing said where documentation should go, and in particular nothing
mentioned that the website appends a whole package README onto a
published page, so a contributor with package scoped prose had no reason
to use that route.

This replaces the four line "Documentation is organized as follows" list
in `docs/agents/overview.md` with a destination table and the test that
separates `docs/` from the website: whether a non-documentation file has
to link to the document by path. It also says that a merged document
records current behaviour and its limitations, not the development
process around it, which is the "What is NOT in Phase N" and "this PR"
residue that motivated the whole thing.

One such residue dropped while here, `docs/operations/backup-classes.md`
described a pin as one "this PR removes".

Moving the documents themselves is a separate PR.

### Downstream repositories

- [x] No downstream repository is affected by this change

Walked the trigger map against the diff: this touches
`docs/agents/overview.md` and `docs/operations/backup-classes.md` only.
No package added, renamed or removed, no `values.yaml` or
`values.schema.json` field, no `packages/core/platform/values.yaml` key,
no bundle or variant, no release asset name, no `ApplicationDefinition`
semantics, no Talos pin, and no change to `cozyvalues-gen`, `cozypkg` or
a package Makefile.

### Release note

```release-note
NONE
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Added guidance for choosing where new documentation belongs, including
package READMEs, the website, repository docs, API design documents, and
community resources.
- Clarified package README publishing and sync conditions, when
repository documentation is warranted, and where to document feature
limitations and development-process notes.
- Clarified that documents referencing unmerged pull requests or
unreleased dependencies need a tracking issue.
- Updated the CloudNativePG upgrade note to explain that the CRD version
skew came from an image tag pin outrunning the vendored chart CRDs; the
pin has since been removed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

docs/agents/overview.md

@@ -136,13 +136,23 @@ Set `upgradeCRDs: CreateReplace` for operators whose upstream regularly adds new
 
 Do **not** set `CreateReplace` blindly: it overwrites every CRD in `crds/` and can cause silent data loss if upstream drops a field from a CRD that has live objects. Only enable it for operators whose schema evolution is additive-only. When in doubt, leave it unset and apply new CRDs manually.
 
-### Documentation
+### Documentation — where a new document goes
 
-Documentation is organized as follows:
-- `docs/` - General documentation
-- `docs/agents/` - Instructions for AI agents
-- `docs/changelogs/` - Release changelogs
-- Main website: https://github.com/cozystack/website
+Product documentation lives in [`cozystack/website`](https://github.com/cozystack/website), not here. This repository holds only documentation that something in the repository references by path, or that describes the repository's own machinery. Pick the destination before writing, because moving a document later means chasing every `@param`, template comment and test comment that points at it.
+
+| Destination | What belongs there |
+| --- | --- |
+| `packages/<group>/<name>/README.md` | Anything scoped to a single package. Prose goes **above** `## Parameters`; that section is `cozyvalues-gen` output and is never hand-edited. The website's `make update-apps` / `update-vms` / `update-networking` / `update-k8s` / `update-services` targets append the whole README onto a published page, but only for the packages named in the `APPS`, `VMS`, `NETWORKING`, `K8S` and `SERVICES` lists of the website `Makefile`, and only from `packages/apps/` and `packages/extra/`: nothing under `packages/system/` is ever imported, and neither is a package that is not on those lists. The sync runs when a release is promoted or tagged, or by hand in the website repository, not when a pull request merges here. Use this route only for a package that is on the lists; for any other the prose reaches no reader, so put it on the website instead. |
+| `cozystack/website`, under `content/en/docs/` | Operator- and tenant-facing content that spans packages or is task-shaped: guides, how-tos, troubleshooting runbooks, reference tables. Which version directory a page goes into is set by the website's own [`CONTRIBUTING.md`](https://github.com/cozystack/website/blob/main/CONTRIBUTING.md); follow that file rather than a copy of its rules here. |
+| `docs/` | Documentation that a chart template, migration, script or workflow references by repo-relative path, plus this repository's own process docs (`docs/agents/`, `docs/changelogs/`, `docs/release.md`). |
+| `api/<group>/<version>/DESIGN.md`, `pkg/apis/<group>/DESIGN.md` | Design of an API group, beside the types it describes. |
+| [`cozystack/community`](https://github.com/cozystack/community) | Design proposals and RFCs. Not this repository. |
+
+When a document could go in either `docs/` or the website, the test is whether a non-documentation file has to link to it by path. `docs/operations/seaweedfs-431-rename-recovery.md` stays because `packages/*/seaweedfs/templates/_naming.tpl` and a platform migration point at it. A guide referenced only from a `values.yaml` `@param` does not qualify — put it on the website and link the URL.
+
+Documenting a feature's current limitations is useful and belongs with the feature. Documenting the *development process* around it does not: no "What is NOT in Phase N", no "out of scope for this PR", no "this PR" phrasing, no action plans or review negotiation. A merged document describes what the code does now, and states a limitation as a limitation rather than as a roadmap position. Scope, phasing and follow-ups belong in the pull request description or an issue.
+
+A document that names an unmerged pull request or an unreleased dependency needs a tracking issue, because nothing re-checks that claim later and it silently becomes false once the thing ships.
 
 ### Domain references for specific tasks
 

docs/operations/backup-classes.md

@@ -357,7 +357,7 @@ If a deployment runs against an external S3 (no SeaweedFS), set `backupStorage.p
 >
 > **Two platform-level changes ride along with this migration (they are required for the plugin to run):**
 >
-> - **CloudNativePG operator bumped to 1.28.1** (`postgres-operator` chart). A minor operator upgrade for the whole fleet; the CNPG CRDs move with it. This also fixes a latent bug where the operator image was newer than its bundled CRDs (`status.instanceID.sessionID` pruned), which made the operator believe the instance manager restarted and fail **every** backup cluster-wide with `instance manager was restarted during backup`. The vendored chart ships the CNPG CRDs as ordinary release manifests (gated by `crds.create`), so a normal `helm upgrade` updates them together with the operator — the `helm.sh/resource-policy: keep` annotation only prevents their deletion, not updates. The historical skew came from the `image.tag` pin outrunning the vendored chart's CRDs, which this PR removes; no out-of-band CRD apply is needed unless the HelmRelease itself is held back.
+> - **CloudNativePG operator bumped to 1.28.1** (`postgres-operator` chart). A minor operator upgrade for the whole fleet; the CNPG CRDs move with it. This also fixes a latent bug where the operator image was newer than its bundled CRDs (`status.instanceID.sessionID` pruned), which made the operator believe the instance manager restarted and fail **every** backup cluster-wide with `instance manager was restarted during backup`. The vendored chart ships the CNPG CRDs as ordinary release manifests (gated by `crds.create`), so a normal `helm upgrade` updates them together with the operator — the `helm.sh/resource-policy: keep` annotation only prevents their deletion, not updates. The historical skew came from the `image.tag` pin outrunning the vendored chart's CRDs; that pin has since been removed, so no out-of-band CRD apply is needed unless the HelmRelease itself is held back.
 > - **LINSTOR scheduler admission webhook must not strip native-sidecar fields.** Older `linstor-scheduler` extender builds (≤ v0.3.5's predecessors) decoded every pod through a stale vendored Kubernetes API and re-encoded it, stripping `initContainers[].restartPolicy` cluster-wide — which breaks the plugin's restartable barman sidecar ("startupProbe forbidden without restartPolicy=Always"). The platform already ships the fixed webhook (`linstor-scheduler` re-vendored to upstream chart 0.3.1 / extender v0.3.6, which stopped stripping unknown pod fields), so no action is needed on an up-to-date platform; just do not hold the `linstor-scheduler` package back on an older version when rolling out the plugin.
 >
 > The same `useSystemBucket` opt-in applies to ClickHouse — see [ClickHouse: opt-in to the system bucket](#clickhouse-opt-in-to-the-system-bucket). When `useSystemBucket: true` is set on ClickHouse, the legacy `<release>-backup` CronJob, credential Secret, and backup script are no longer rendered (they are mutually exclusive with the platform flow); migrate scheduled backups to a `backups.cozystack.io/Plan` against `cozy-default`.