Wrapper tool hardening and cleanup

WIKI_DEPLOYMENT_CONTRACT.md

@@ -0,0 +1,108 @@
+# Wiki Deployment Contract
+
+## Scope
+
+This contract governs the next focused phase after wrappers, config refactor,
+logging, and topdata hardening:
+
+- `toolkit/` owns `build-wiki` and `deploy-wiki`
+- `module/` owns the consuming release workflow and operational configuration
+
+This work is intentionally sequenced after topdata hardening because the wiki
+pipeline consumes native topdata outputs and metadata.
+
+## Current State
+
+As of 2026-05-13:
+
+- `build-wiki` exists
+- `deploy-wiki` exists
+- deployment targets NodeBB core `/api/v3`
+- local deploy manifests and NodeBB topic mapping exist
+- release automation in `module/scripts/release-all.sh` already runs wiki build
+  and deploy steps after release publication
+- toolkit tests already cover dry-run behavior, topic creation, and manifest
+  writes
+
+This means wiki deployment is no longer a greenfield feature. The next phase is
+hardening, integration clarity, and operator experience.
+
+## Deferred Until Current Priority Work Completes
+
+Do not prioritize the following until wrappers/config/logging/topdata work is in
+better shape:
+
+- new NodeBB release-announcement posting flows
+- broad wiki feature expansion
+- unrelated formatting changes to generated page content
+
+## Immediate Goals For The Wiki Phase
+
+1. align wiki build/deploy logs with the structured logging contract
+2. tighten config ownership for wiki defaults and category mappings
+3. reduce residual hardcoded behavior that belongs in normalized config
+4. improve release-flow clarity around dry-run, drift, create, and force modes
+5. verify that topdata hardening does not silently change generated page identity
+
+## Current Findings
+
+- `deploy-wiki` already reads managed namespaces from effective config when the
+  caller does not specify them explicitly
+- deploy manifest naming and edit-summary defaults still come from toolkit
+  defaults in `internal/project/effective.go`
+- release orchestration already guards publication order correctly, but the
+  operator-facing logs are still more shell-oriented than the newer structured
+  `build-haks` presentation
+- wiki deployment should be treated as a first-class operational command family,
+  not just a release-script tail step
+
+## Immediate Plan
+
+### Phase 1: Logging and UX parity
+
+- add concise summaries for `build-wiki` and `deploy-wiki`
+- surface counts for:
+  - pages collected
+  - creates
+  - updates
+  - skips
+  - drifted pages
+- keep raw debug output available when diagnosis is needed
+
+### Phase 2: Config clarity
+
+- audit which wiki defaults should remain toolkit defaults versus explicit repo
+  config
+- keep namespace/category ownership visible in effective config
+- ensure deploy-manifest path and edit summary remain discoverable and easy to
+  override
+
+### Phase 3: Release-flow hardening
+
+- verify `module/scripts/release-all.sh` remains the authoritative release entry
+  point
+- keep dry-run before live deploy
+- ensure failure and drift messages are crisp and actionable
+- make sure cache restore/save behavior is clearly documented and tested
+
+### Phase 4: Regression verification after topdata hardening
+
+- confirm topdata de-hardcoding does not break page IDs or manifest mapping
+- confirm generated-page identity remains stable across unchanged inputs
+
+## Testing Requirements
+
+Add or expand tests for:
+
+- app-layer output for `build-wiki` and `deploy-wiki`
+- release-flow sequencing assumptions where wiki deploy must happen only after
+  release assets are published
+- stable page identity and manifest mapping across repeated runs
+- config-driven namespace selection and manifest path overrides
+
+## Acceptance Criteria
+
+- wiki build/deploy logs match the newer structured CLI standard
+- wiki defaults and overrides are clearly represented in effective config
+- release orchestration remains deterministic and easy to reason about
+- topdata hardening does not regress page identity or deploy manifest behavior