Target Gitea's package registry in the monorepo migration brief

Replaces the GitHub Packages assumption with the self-hosted Gitea
instance this repo actually runs on: registry URL pattern, owner-vs-repo
scoping, auth token requirements, and that packages need no advance
provisioning (Gitea creates them on first publish).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/MONOREPO_MIGRATION_BRIEF.md

@@ -15,8 +15,12 @@ npm-workspaces monorepo with independently versioned, privately distributed pack
   and composition roots.
 
 The packages must be normal npm-format packages, but they must not be published to the public
-npmjs.com registry. Configure them for a private registry (GitHub Packages is the assumed default;
+npmjs.com registry. This repository is hosted on a self-hosted Gitea instance; use Gitea's built-in
-substitute the actual internal registry if different).
+package registry (npm support since Gitea 1.17) rather than provisioning a separate service. A Gitea
+package belongs to an owner (a user or organization), not to a git repository — the owner does not
+need to be the same account that hosts this source repo, though keeping them aligned is simpler to
+reason about. A package needs no advance provisioning: Gitea creates it automatically on the first
+`npm publish` under that owner.
 
 This migration is about packaging, ownership, and build boundaries. Preserve existing runtime
 behavior and wire protocols unless a change is specifically required to establish a package API.
@@ -53,8 +57,12 @@ can be changed and tested together.
    migration accidentally.
 3. Record a green baseline with the existing `check`, unit-test, lint, and build commands. If the
    baseline is not green, distinguish pre-existing failures from migration regressions.
-4. Decide the private package scope, replacing every `@<scope>` placeholder below. Do not invent a
+4. Decide the private package scope, replacing every `@<scope>` placeholder below, and decide the
-   scope if the repository or organization configuration does not reveal it.
+   Gitea host and owner (user or organization) the packages will publish under, replacing every
+   `<gitea-host>`/`<owner>` placeholder below. The npm `@<scope>` string and the Gitea `<owner>` path
+   segment are independent and do not have to match, but keeping them identical avoids confusion. Do
+   not invent a scope, host, or owner if the repository or organization configuration does not reveal
+   it.
 
 ## Target repository structure
 
@@ -183,7 +191,7 @@ Create curated index files and export only supported APIs. A starting manifest s
 		}
 	},
 	"publishConfig": {
-		"registry": "https://npm.pkg.github.com"
+		"registry": "https://<gitea-host>/api/packages/<owner>/npm/"
 	}
 }
 ```
@@ -280,7 +288,7 @@ so the app owns the single compatible core installation:
 		}
 	},
 	"publishConfig": {
-		"registry": "https://npm.pkg.github.com"
+		"registry": "https://<gitea-host>/api/packages/<owner>/npm/"
 	}
 }
 ```
@@ -406,14 +414,29 @@ silently into the app.
 
 ## Private publication and versioning
 
-Assuming GitHub Packages, add this committed scope mapping without a token:
+Use Gitea's built-in package registry at `https://<gitea-host>/api/packages/<owner>/npm/`. Add this
+committed scope mapping without a token:
 
 ```ini
-@<scope>:registry=https://npm.pkg.github.com
+@<scope>:registry=https://<gitea-host>/api/packages/<owner>/npm/
+```
+
+Authentication is a separate, uncommitted line — a Gitea personal access token (or, in CI, a repo- or
+org-level token) with `package` permission:
+
+```ini
+//<gitea-host>/api/packages/<owner>/npm/:_authToken=${GITEA_NPM_TOKEN}
 ```
 
 Authentication belongs in developer and CI secrets. Never commit a package token.
 
+Gitea does not require a package to be created ahead of time — it is created automatically on the
+first `npm publish` under that owner and appears afterward on the owner's Packages tab. Publish access
+to an org-owned package is restricted to org members with admin or write access to that org, so decide
+who that is before the first release. Linking a published package back to this source repository (for
+discoverability in the repo's own UI) is optional, is done from the package's settings page after
+publishing, and has no effect on `npm install`/`npm ci`.
+
 Version core and humanoid independently. Start both at `0.1.0` unless existing internal releases
 require another baseline. During `0.x` development, document that minor releases may be breaking;
 after `1.0.0`, use normal semantic-versioning expectations.