# 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