ForgeFlow / Reference

Maintaining The Wiki

The canonical Markdown lives in docs/wiki/ in the ForgeFlow source repository. GitHub serves the wiki from a separate ForgeFlow.wiki.git repository. A push to the product repository does not update the published wiki automatically.

Keep The Surfaces Aligned

Edit the source pages first. Keep current setup and workflow instructions separate from historical release evidence. Update the Home topic index and sidebar when adding a page. Link to other source pages with .md extensions; use relative repository paths for images and other documentation.

The local exporter converts page links to GitHub wiki routes and repository assets to absolute GitHub URLs. Images use raw image URLs. HTML guides and changelogs link to their GitHub file pages, where readers can download them. GitHub Pages is not assumed to be enabled.

Build The Visual Reference

The documentation hub and visual guide link to styled HTML reference pages. Keep .md links in the source; the builder converts links between wiki topics to .html and preserves section anchors. The HTML shares docs/guide.css with the documentation hub and works from a local checkout without a server.

npm ci
npm run docs:build
npm run docs:check

Regenerate the pages after editing Markdown or the builder, and include the generated HTML with the source change. Review a setup page and a table-heavy page at desktop and mobile widths. Repository implementation references remain links to GitHub source. The separate GitHub wiki export remains Markdown.

Prepare A Local Export

From the ForgeFlow source checkout:

node scripts/forgeflow/test-doc-links.js
node scripts/forgeflow/test-release-version.js
node scripts/forgeflow/test-export-wiki.js

Clone the published wiki into a separate directory outside the source checkout. Choose a new path, or use an existing clean wiki checkout after inspecting its status and fetching current changes.

git clone https://github.com/BrandedTamarasu-glitch/ForgeFlow.wiki.git /path/to/ForgeFlow.wiki
git -C /path/to/ForgeFlow.wiki status --short
node scripts/export-wiki.js --out /path/to/ForgeFlow.wiki
git -C /path/to/ForgeFlow.wiki diff --stat
node scripts/export-wiki.js --out /path/to/ForgeFlow.wiki --check

The exporter writes local Markdown only. It preserves .git and unrelated assets, rejects unexpected wiki-only Markdown pages so they can be reconciled explicitly, and never commits, pushes, or deletes pages. --check reports drift without writing. Review the full diff and check the Home page, sidebar, guide/PDF links, and dashboard image before publishing.

Publish And Verify

Publish only when a maintainer has authorized the repository and wiki changes. Commit and push the source documentation first so exported links resolve to the corresponding files on main. Then stage the reviewed Markdown files by name in the wiki checkout, commit them, and push that separate repository. Do not stage private audit notes or local workflow state.

After publishing as part of an authorized release, verify the GitHub wiki Home page, sidebar, a setup page, the dashboard image, and both guide links. Compare the published wiki HEAD with the local commit and rerun the exporter with --check. Run source validation locally; GitHub Actions is disabled for the product repository. Local checks do not prove the published wiki's rendered links work.

If someone has edited the wiki directly, bring useful changes back into docs/wiki/ before the next export. Do not overwrite an unexplained remote edit. Keep Release Process, the README, the documentation entry, and the wiki consistent when the product changes.