docs(16.3): insert phase 16.3 and promote the API tokens todo

.planning/ROADMAP.md

@@ -1016,6 +1016,29 @@ Plans:
 **Wave 4** *(blocked on Wave 3 completion)*
 - [ ] 16.2-06-PLAN.md — Unit tests: resave contract at every layer, strip-and-report and notices, policy cross-check corpus (both policies, identical copies), category strip, full Go and JS coverage, Postgres tests for a Docker host, phase gate scripts/check-phase16.2.sh, validation map
 
+### Phase 16.3: Backend admin personal API tokens with scopes (INSERTED)
+
+**Goal:** Backend users can create personal API tokens with a scope they pick at creation time (for example Journal only, or system-wide; later read-only Payment Gateway), so an agent or integration can call the admin and plugin APIs as that backend user, with no more access than the token's scope and the user's own permissions allow. This is the successor of Apparatus `PersonalApiToken` (todo `backend-admin-api-tokens.md`, note `apparatus-dissolved-into-framework.md`) and reverses the Phase 15 D-15 rule that Journal writes accept only a backend JWT.
+**Requirements**: TBD
+**Depends on:** Phase 9, Phase 10, Phase 15
+**Repos:** `summercms.go` (bouncer guard, token model and migration, scope registry, admin SPA panel, CLI); `sm-journal-plugin` to register its scope and accept tokens on its write routes; host applications only for the version bump
+**Constraints from explore (2026-10-10):**
+  - Tokens keep the `g15_` prefix and are stored only as a hash. The rest of the format can change, and WinterCMS Apparatus tokens are not migrated.
+  - The user picks the scope when creating a token. Plugins register their own scopes. Scope design (names, read-only variants, system-wide) is settled in discuss-phase.
+  - Tokens are managed in two places, as in WinterCMS: a panel on the admin SPA backend user form (create, show once, revoke) and a `summer` CLI command.
+**Success Criteria** (what must be TRUE):
+
+  1. The `backend` guard accepts a valid, unexpired, unrevoked `g15_` token as well as the backend JWT, and the request runs as the token's backend user.
+  2. A request outside the token's scope is refused even when the user's role would allow it, and a token never grants more than its owner's permissions.
+  3. A backend user can create, list and revoke their own tokens in the admin SPA. The plaintext token is shown once. A CLI command does the same for any backend user.
+  4. The Journal API accepts a Journal-scoped token for writes, so an agent can manage blog posts as a backend author.
+  5. Module READMEs and `docs/` cover the token API, scopes and CLI commands.
+  6. The new code has unit tests, delivered in the phase's last plan.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 16.3 to break down)
+
 ### Phase 17: Blog companions
 
 **Goal:** The sitemap, menu and FAQ plugins run on SummerCMS as shared `sm-*-plugin` repos, so a blog site can manage its menus, FAQs and sitemap in the admin again instead of hardcoding them in the Nuxt app.

.planning/STATE.md

@@ -4,13 +4,13 @@ milestone: v1.0
 current_phase: "16.2"
 current_phase_name: Plugin-provided field types and the Blog Editor formwidget
 status: executing
-stopped_at: Completed 16.2-05-PLAN.md
-last_updated: "2026-10-10T12:01:49.546Z"
+stopped_at: Phase 16.3 context gathered
+last_updated: "2026-10-10T13:33:03.540Z"
 last_activity: 2026-10-10
 last_activity_desc: Phase 16.2 execution started
-state_head: 85fe541b03885fbb34c7d66e7ed9bbdfc583ffbe
+state_head: c07da3912b1cc4b5d112200f7af16c5ad3061d02
 progress:
-  total_phases: 34
+  total_phases: 35
   completed_phases: 13
   total_plans: 157
   completed_plans: 152
@@ -232,6 +232,7 @@ Progress: [██████████] 100%
 - Phase 18.1 inserted after Phase 18: Payment Gateway Subscriptions (split from Phase 18 per 18-CONTEXT D-01)
 - Phase 16.1 inserted after Phase 16: Journal admin urgent fixes: relation search, list state, post form content and excerpt (found on UAT) (URGENT)
 - Phase 16.2 inserted after Phase 16.1: Plugin-provided field types and the Blog Editor formwidget
+- Phase 16.3 inserted after Phase 16: Backend admin personal API tokens with user-selected scopes (Journal agent writes as backend author); successor of Apparatus PersonalApiToken (URGENT)
 
 ### Decisions
 
@@ -747,6 +748,6 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-10-10T11:36:12.850Z
-Stopped at: Completed 16.2-05-PLAN.md
-Resume file: None
+Last session: 2026-10-10T13:33:02.885Z
+Stopped at: Phase 16.3 context gathered
+Resume file: .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-CONTEXT.md

.planning/phases/16.1-journal-admin-urgent-fixes-relation-search-list-state-post-f/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/16.2-plugin-provided-field-types-and-the-blog-editor-formwidget/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/18.1-payment-gateway-subscriptions/.gitkeep

@@ -0,0 +1 @@
+

.planning/state.json

@@ -144,5 +144,5 @@
     "label": "Advance to the next step",
     "reason": "Phase 16.2 of 34 · executing"
   },
-  "updated_at": "2026-10-10T11:36:07.796Z"
+  "updated_at": "2026-10-10T12:47:48.195Z"
 }

.planning/todos/pending/backend-admin-api-tokens.md

@@ -1,10 +1,12 @@
 ---
-title: Backend admin personal API tokens (deferred Apparatus PersonalApiToken)
+title: Backend admin personal API tokens (Phase 16.3)
 date: 2026-09-28
-priority: low
+priority: high
 area: summercms.go admin auth
 ---
 
 Apparatus provides personal API tokens for backend admins (`PersonalApiToken` model, `TokenAuthenticate` + `ForceJsonResponse` middleware, token create/revoke on the backend user form). Nothing in Płytarium calls it, so it is deferred past v1. The Phase 9 `backend` guard already accepts `Authorization: Bearer` for CLI and tests.
 
 Revisit when a Golem15 project needs scripted access to the admin API. See `.planning/notes/apparatus-dissolved-into-framework.md`.
+
+**2026-10-10:** Promoted to Phase 16.3 (scoped tokens, Journal agent use case). No migration of Apparatus tokens.