Clarify partial data transfer behavior and restructure the transfer page

claude-plugins/inki/references/prompts/integrity-known-pitfalls.md

@@ -40,6 +40,17 @@ This file lists documented patterns where AI-generated documentation has produce
 | `const { primitives } = require('@strapi/utils')` | `const { strings, objects, arrays, dates } = require('@strapi/utils')` | `@strapi/utils` does `export * from './primitives'` (flattened), not `export * as primitives` |
 | `validateYupSchema` under the `yup` namespace | `validateYupSchema` is a top-level export from `@strapi/utils` | Exported from `./validators`, not from `./yup`. Import as `const { validateYupSchema } = require('@strapi/utils')`. |
 
+### Data transfer stage filtering
+
+Verified against `packages/core/strapi/src/cli/utils/data-transfer.ts` (`parseRestoreFromOptions`, `expandMediaLibraryPreset`), `packages/core/data-transfer/src/engine/index.ts` (`TransferGroupPresets`), and `packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts` (`deleteEntitiesRecords`).
+
+| Hallucinated pattern | Correct pattern | Context |
+|---------------------|-----------------|---------|
+| `--exclude files` (or `--only content`) described as preserving "files" or "the media library" on the destination | It preserves only the **binaries** under `public/uploads`. Media library DB records (`plugin::upload.file`, `plugin::upload.folder`) are part of the `content` preset and still transfer. Only `--exclude media-library` preserves both. | `TransferGroupPresets.files` is `{assets: true}` only; upload records ride the `entities` stage with `content`. Data-loss-adjacent: the wrong claim leaves the destination with records pointing at binaries that were never transferred. Always state which of the two halves is preserved, never just "files". |
+| A stage-filtering matrix whose default-command row claims nothing is preserved on the destination | The default command always preserves `admin::*` types and `IGNORED_CONTENT_TYPES` (`plugin::content-releases.release`, `…release-action`) | `entitiesOptions.exclude` unconditionally contains the admin-prefixed and ignored types, so content is never wiped entirely. A "None preserved" row is always wrong. |
+| `--exclude` / `--only` described as **deleting** the omitted types on the target instance (any data-management page) | Omitted stages are **preserved**; only transferred stages are replaced | `strapi import` and `strapi transfer` both call the same `parseRestoreFromOptions`, so the semantics are identical across the two pages. When a stage is out of scope, `entities.include` is set to `[]`, which matches nothing and short-circuits deletion. Check `import.md`, `export.md`, `transfer.md`, and `cli.md` agree: they have contradicted each other before. |
+| A docs page quoting a `strapi transfer` confirmation prompt as "will delete all of the remote Strapi assets and its database" | The remote prompt is "The transfer will delete existing data from the remote Strapi!"; the local one is "…delete all **the** local Strapi assets and its database" | Reworded upstream precisely because `--only`/`--exclude` mean a transfer no longer always deletes everything. Verify quoted prompt strings against `packages/core/strapi/src/cli/commands/transfer/command.ts` rather than copying older docs. |
+
 ### Documentation formatting conventions
 
 These are not code hallucinations but recurring Strapi-docs formatting mistakes. Verified against `STYLE_GUIDE.pdf` and `docusaurus/src/components/Icon.js`.

claude-plugins/inki/references/templates/components/badge.md

@@ -50,10 +50,67 @@ These props belong to the underlying `<Badge>` component. The alias variants pre
 3. **Do not invent variants.** Stick to the twelve registered aliases. There is no `FreeBadge` and no `CloudDevBadge`; the Cloud Starter alias is `CloudStarterBadge`.
 4. **Badges are self-closing JSX.** Write `<NewBadge />`. A space before `/>` is fine, and `<GrowthBadge/>` also works.
 5. **Inside a heading, place the badge before the `{#anchor}` token.** For example, `## Strapi AI <NewBadge /> {#strapi-ai}`.
-6. **Use `noTooltip` in tables and headings** where a hover tooltip would be awkward or cut off (e.g. `<FeatureFlagBadge feature="FeatureFlagName" noTooltip />`).
+6. **Use `noTooltip` in tables and inline in prose**, where a hover tooltip would be awkward or cut off (e.g. `<FeatureFlagBadge feature="FeatureFlagName" noTooltip />`). Under a heading, keep the tooltip: see "Placement: heading versus inline" below.
 7. **`feature` and `version` override the variant-based class.** Setting `feature` forces `badge--featureflag` and setting `version` forces `badge--version`; these win over the `variant`-derived class.
 8. **Override the tooltip when the default is wrong.** Pass `tooltip="..."` to replace the pre-filled text rather than leaving an inaccurate default.
 
+## Placement: heading versus inline
+
+`VersionBadge` (and any badge) has two distinct placements. Picking the wrong one is a common mistake, so decide first which case you are in.
+
+### Case 1: the badge qualifies a whole section or page
+
+Put the badge on **a dedicated badge line directly under the heading** (`h1`, `h2`, `h3`, or deeper), and **keep the tooltip**. The line has room for it, and the tooltip is what tells the reader what the badge actually gates.
+
+That line is a shared slot, not one badge per line: put **every badge that qualifies the section on it**, space-separated, on a single line. Never stack them on consecutive lines.
+
+```mdx
+## Filter content types during transfer
+
+<VersionBadge version="5.50.3" />
+
+The `--exclude-content-types` and `--only-content-types` options let you …
+```
+
+Several flags on the same heading, all on one line — typically plan badges, then maturity, then version:
+
+```mdx
+# Content History
+
+<GrowthBadge /> <EnterpriseBadge/> <VersionBadge version="5.0.0" />
+```
+
+When the heading introduces a *newly documented behavior* rather than a brand-new option, override the tooltip so readers do not conclude the whole feature is new:
+
+```mdx
+## What a transfer replaces and preserves
+
+<VersionBadge version="5.52.2" tooltip="The preserve-versus-replace behavior described below is clarified and logged by the CLI since Strapi 5.52.2." />
+```
+
+### Case 2: the badge qualifies one sentence, row, or option
+
+Put the badge **on the same line as the content it qualifies**, and add **`noTooltip`**: an inline tooltip overlaps the surrounding text and gets cut off. Since the tooltip is no longer there to carry the meaning, weave the badge into the sentence so it reads as part of the prose, rather than parking it at the start of the line.
+
+```mdx
+With Strapi <VersionBadge version="5.42.1+" noTooltip />, for localizable relations, Strapi automatically fetches the corresponding entry in the target locale if it exists.
+```
+
+Same rule inside a table cell:
+
+```mdx
+| `--only-content-types` | <VersionBadge version="5.50.3" noTooltip /> Comma-separated list of content-type UIDs to include. |
+```
+
+### Quick decision
+
+| The badge applies to… | Placement | Tooltip |
+|---|---|---|
+| A heading's whole section or page | Shared badge line under the heading, all badges space-separated on it | Keep it; override the text when the version gates a clarified behavior rather than a new feature |
+| One sentence, list item, or table row | Same line as the content, woven into the sentence | `noTooltip`, and state the version in the prose |
+
+Do not put a badge on a line of its own in the middle of prose: it reads as applying to everything that follows, which is exactly what Case 1 means.
+
 ## Canonical examples
 
 ### Plan and version badges chained on one line

docusaurus/docs/cms/cli.md

@@ -229,7 +229,7 @@ The exported file is automatically named using the format `export_YYYYMMDDHHMMSS
 | `--format`          | string | Export format: `tar` (default) or `dir`. Directory exports require `--no-encrypt`.                                         |
 | `--exclude`         | string | Exclude data using comma-separated data types. The available types are: `content`, `files`, `config`, and `media-library` (excludes both upload binaries and upload content type records). |
 | `--only`            | string | Include only these data. The available types are: `content`, `files`, and `config`.                                        |
-| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the export. Both entity records and relation links are excluded. |
+| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the export. Both entity records and relation links touching an excluded type are skipped. |
 | `--only-content-types` | string | Comma-separated list of content-type UIDs to include in the export.                                                  |
 | `-h`, <br/>`--help` |   -    | Displays help for the `strapi export` command.                                                                             |
 
@@ -267,7 +267,7 @@ The command accepts archives generated by `strapi export` (`.tar`, `.tar.gz`, `.
 | -------------- | ------ | ------------------------------------------------------------------------------------- |
 | `-k,` `--key`  | string | Provide the encryption key in the command instead of a subsequent prompt.             |
 | `-f`, `--file` | string | Path to a `.tar[.gz][.enc]` archive or to an unpacked export directory.               |
-| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the import. Excluded types are preserved on the destination. |
+| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the import. Both entity records and relation links touching an excluded type are skipped, and the excluded types are preserved on the destination. |
 | `--only-content-types` | string | Comma-separated list of content-type UIDs to include in the import.                  |
 | `-h`, `--help` | -      | Display the `strapi import` help commands.                                            |
 
@@ -298,12 +298,15 @@ The destination Strapi instance should be running with the `start` command and n
 | `--to [destinationURL]`      | Full URL of the `/admin` endpoint on the destination Strapi instance<br />(e.g. `--to https://my-beautiful-strapi-website/admin`)                 |
 | `--to-token [transferToken]` | Transfer token for the remote Strapi destination                                                                                                  |
 | `--from [sourceURL]`         | Full URL of the `/admin` endpoint of the remote Strapi instance to pull data from<br />(e.g., `--from https://my-beautiful-strapi-website/admin`) |
-| `‑‑from‑token`               | Transfer token from the Strapi source instance.                                                                                                   |
+| `--from-token`               | Transfer token from the Strapi source instance.                                                                                                   |
 | `--force`                    | Automatically answer "yes" to all prompts, including potentially destructive requests, and run non-interactively.                                 |
 | `--exclude`                  | Exclude data using comma-separated data types. The available types are: `content`, `files`, `config`, and `media-library` (excludes both upload binaries and upload content type records). |
 | `--only`                     | Include only these data. The available types are: `content`, `files`, and `config`.                                                               |
-| `--exclude-content-types`    | Comma-separated list of content-type UIDs to exclude. Both entity records and relation links are excluded.                                        |
+| `--exclude-content-types`    | Comma-separated list of content-type UIDs to exclude. Both entity records and relation links touching an excluded type are skipped.               |
 | `--only-content-types`       | Comma-separated list of content-type UIDs to include. Only entity records and relation links for the listed types are transferred.                |
+| `--throttle`                 | Time in milliseconds to inject an artificial delay between each transferred entity.                                                               |
+| `--no-checksums`             | Disable end-to-end SHA-256 checksum verification for assets. Checksum verification is enabled by default when both the source and destination instances support it. |
+| `--verbose`                  | Enable verbose logs.                                                                                                                              |
 | `-h`, `--help`               | Displays the commands for `strapi transfer`.                                                                                                      |
 
 :::caution

docusaurus/docs/cms/configurations/database.md

@@ -339,7 +339,7 @@ await pluginStore.set({
 
 Some cloud providers issue short-lived database credentials that expire after a fixed period. For example, AWS RDS IAM tokens are valid for 15 minutes; GCP Cloud SQL IAM tokens expire similarly; HashiCorp Vault can rotate secrets on a schedule. Using a static password in `.env` causes intermittent connection failures when the connection pool recycles idle connections after the token has expired.
 
-Strapi supports dynamic credentials through Knex's connection function pattern. Instead of a plain connection object, you can pass a synchronous or asynchronous function to `connection.connection`. Knex calls this function whenever it needs to open a new database connection, ensuring the pool always receives fresh credentials. This pattern works for PostgreSQL and MySQL/MariaDB. TypeScript types officially accept sync and async functions for `connection.connection` as of Strapi v5.50.3.
+Strapi supports dynamic credentials through Knex's connection function pattern. Instead of a plain connection object, you can pass a synchronous or asynchronous function to `connection.connection`. Knex calls this function whenever it needs to open a new database connection, ensuring the pool always receives fresh credentials. This pattern works for PostgreSQL and MySQL/MariaDB. TypeScript types officially accept sync and async functions for `connection.connection` as of Strapi v5.51.0.
 
 :::tip
 Include an `expirationChecker` property in the object returned by your function. Knex calls this before reusing a connection from the pool; if it returns `true`, Knex discards the existing connection and calls your function again to obtain fresh credentials.

docusaurus/docs/cms/features/data-management/export.md

@@ -314,7 +314,7 @@ npm run strapi export -- --exclude files,content
 
 ## Filter content types during export
 
-<VersionBadge version="5.50.3" />
+<VersionBadge version="5.51.0" />
 
 The `--exclude-content-types` and `--only-content-types` options let you scope an export to specific content types. Both options accept a comma-separated list of content-type UIDs (for example, `api::article.article`). Unknown UIDs are validated against the Strapi schema at startup. Both entity records and any relation links touching an excluded type are skipped automatically.
 

docusaurus/docs/cms/features/data-management/import.md

@@ -219,7 +219,7 @@ npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --
 The default `strapi import` command imports your content (entities and relations), files (assets), project configuration, and schemas. The `--exclude` option allows you to exclude content, files, and the project configuration by passing these items in a comma-separated string with no spaces between the types. You can't exclude the schemas, as schema matching is used for `strapi import`.
 
 :::warning
-Any types excluded from the import will be deleted in your target instance. For example, if you exclude `config` the project configuration in your target instance will be deleted.
+Stages omitted with `--exclude` or `--only` are not wiped in your target instance: their existing data is preserved. For example, if you exclude `config`, the project configuration already present in your target instance is left untouched. Stages that are imported fully replace the corresponding data in the target instance.
 :::
 
 :::note
@@ -280,7 +280,7 @@ npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --only
 
 ## Filter content types during import
 
-<VersionBadge version="5.50.3" />
+<VersionBadge version="5.51.0" />
 
 The `--exclude-content-types` and `--only-content-types` options let you scope an import to specific content types. Both options accept a comma-separated list of content-type UIDs (for example, `api::article.article`). Unknown UIDs are validated against the Strapi schema at startup.