docs: add maintainer operations guide

Author: Dmatut7

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Added GitHub Actions npm Trusted Publishing workflow so tagged releases can publish without local npm tokens or OTP.
+- Added maintainer operations docs for releases, Trusted Publishing, and bundled Codex skill updates.
 
 ## 0.2.4 — 2026-06-05
 

README.md

@@ -172,4 +172,4 @@ npm test            # FakeAdapter only, no network
 
 Regression suite covers keyed replay, dependency-subtree invalidation, schema repair, transient retry, writable-cwd protection, deterministic shadows + stable cache keys, soft-budget skip, crash-residue / non-terminal-repair journal recovery, backend routing, and the CLI (`install-codex` + `run`).
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for local development rules and [docs/CODEX_FOR_OSS_APPLICATION.md](docs/CODEX_FOR_OSS_APPLICATION.md) for the Codex for Open Source application prep notes.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development rules, [docs/MAINTAINER_OPERATIONS.md](docs/MAINTAINER_OPERATIONS.md) for release / skill update operations, and [docs/CODEX_FOR_OSS_APPLICATION.md](docs/CODEX_FOR_OSS_APPLICATION.md) for the Codex for Open Source application prep notes.

docs/MAINTAINER_OPERATIONS.md

@@ -0,0 +1,140 @@
+# Maintainer operations
+
+This file records the project-specific release and Codex skill maintenance steps. It is intentionally operational: follow it when publishing, updating bundled skills, or helping another maintainer refresh their local setup.
+
+## What is already configured
+
+- npm package: `codex-flow`
+- npm owner used here: `tutudma`
+- GitHub repo: `Dmatut7/codex-flow`
+- npm Trusted Publisher: GitHub Actions → `Dmatut7/codex-flow` → `publish.yml`
+- Allowed Trusted Publisher action: `npm publish`
+- Release workflow: `.github/workflows/publish.yml`
+
+The release workflow uses OIDC Trusted Publishing. It must not use `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or checked-in `.npmrc` credentials.
+
+## Normal release flow
+
+Start from a clean `main` branch.
+
+```bash
+git checkout main
+git pull origin main
+git status --short
+npm run typecheck
+npm test
+```
+
+Update `CHANGELOG.md` first. Move the relevant `Unreleased` notes into a dated version section.
+
+Then bump and tag:
+
+```bash
+npm version patch   # or: npm version minor / npm version major
+git push origin main --tags
+```
+
+Pushing the `v*` tag starts GitHub Actions. The workflow verifies the tag matches `package.json`, runs typecheck/tests, then publishes to npm by OIDC.
+
+Check:
+
+```bash
+npm view codex-flow version
+```
+
+If the GitHub Action fails, fix the repo/workflow and push a new commit/tag as appropriate. Do not fall back to local token publishing unless Trusted Publishing itself is unavailable.
+
+## One-time npm Trusted Publisher setup
+
+This was already done for `codex-flow`, but if the package is recreated or moved:
+
+1. Open `https://www.npmjs.com/package/codex-flow/access`.
+2. In **Trusted Publisher**, choose **GitHub Actions**.
+3. Fill:
+   - Organization or user: `Dmatut7`
+   - Repository: `codex-flow`
+   - Workflow filename: `publish.yml`
+   - Environment name: leave blank unless the workflow adds a GitHub environment
+4. Allow only `npm publish`.
+5. Confirm password / 2FA.
+6. Verify the page shows `Dmatut7/codex-flow`, `publish.yml`, and permission `npm publish`.
+
+CLI equivalent, if npm authentication supports trust endpoints:
+
+```bash
+npx npm@^11.10.0 trust github codex-flow \
+  --repo Dmatut7/codex-flow \
+  --file publish.yml \
+  --allow-publish \
+  --yes
+```
+
+## Updating Codex skills after someone changes this repo
+
+The bundled skills live in:
+
+- `codex-skill/` → installs as `dynamic-workflow`
+- `codex-skill-business-audit/` → installs as `business-defect-audit`
+- `codex-skill-parallel-fix/` → installs as `parallel-fix`
+
+For users installed from npm:
+
+```bash
+npm install -g codex-flow@latest
+codex-flow install-codex
+codex-flow doctor
+# restart Codex App or Codex CLI
+```
+
+For maintainers working from a local checkout:
+
+```bash
+git pull origin main
+npm install
+node bin/codex-flow.mjs install-codex
+node bin/codex-flow.mjs doctor
+# restart Codex App or Codex CLI
+```
+
+`install-codex` replaces stale installed skill folders. That is expected.
+
+## What not to commit
+
+These are local run artifacts and should stay untracked:
+
+- `.codex-flow/` journals and generated temporary workflows
+- `.codex-workflow/`
+- `.dongt/`
+- `node_modules/`
+- temporary `.npmrc` files containing publish tokens
+- screenshots or one-off browser artifacts from npm/GitHub setup
+
+If a temporary workflow is useful as a reusable example, copy a cleaned, import-free version into `examples/` and add tests/docs for it. Do not commit raw `.codex-flow/generated/*` files.
+
+## Changing bundled skills
+
+When editing any bundled skill:
+
+1. Edit the source folder in this repo, not `~/.codex/skills`.
+2. Run:
+
+```bash
+npm run typecheck
+npm test
+node bin/codex-flow.mjs install-codex --dir "$(mktemp -d)"
+```
+
+3. If the change is user-visible, update `CHANGELOG.md`.
+4. Commit the repo change. Users get it by reinstalling `codex-flow@latest` and running `codex-flow install-codex`.
+
+## Emergency local publish fallback
+
+Only use this if GitHub Actions / OIDC is down and the release cannot wait.
+
+```bash
+npm run typecheck
+npm test
+npm publish --access public
+```
+
+Do not save tokens in the repo. If a temporary npm token or temporary npmrc is used, delete it immediately after publishing.