Forge Intelligence

Handbook

Documentation dual-wiki requirements

Canonical contract for the documentation dual-wiki — operator (user/platform concepts) paired with system (maintainer/backend depth).

Updated

Four dual-wiki patterns (glossary)

Name Canonical Derived Scope
Handbook pair fi docs/*.md fiw website/*.html Product documentation published as HTML
Documentation dual-wiki docs/handbook/operator/ docs/handbook/system/ Platform handbook information architecture
Concept dual-wiki wiki/semantic/ (LMETA) wiki/execution/ (LCDL) Per intelligence_id overlay parity
Session dual-wiki sessions/<id>/machine/*.json sessions/<id>/human/report.md Per execution session audit trail

Do not conflate these patterns. Full spec: DUAL-WIKI.md.

Stable feature identifiers

Every material platform capability receives a stable ID:

FI-<DOMAIN>-<NNN>

Examples:

  • FI-CORE-001 — Platform overview
  • FI-CORE-002 — Reasoning economy
  • FI-MODE-001 — General vs specific intelligence
  • FI-PACK-001 — Domain packs
  • FI-SESS-001 — Session audit trail
  • FI-BND-001 — Product boundaries
  • FI-CONC-001 — Concept documentation (semantic/execution overlays)

Do not encode file paths, Python module names, or vendor names in feature IDs.

Register every ID in feature-index.md and traceability-matrix.md.

Page contracts

Operator page frontmatter

---
feature_id: FI-CORE-001
title: Platform overview
audience: operator
paired_page: ../system/overview.md
status: published
nav_order: 10
---

System page frontmatter

---
feature_id: FI-CORE-001
title: Platform overview (system)
audience: system
paired_page: ../operator/overview.md
status: published
nav_order: 10
---

Required fields: feature_id, title, audience, paired_page, status.

Operator page contract

Every operator page must answer:

  1. Who is this for?
  2. What problem does it solve?
  3. What can the operator do?
  4. What can the operator not do?
  5. What are the important limitations?
  6. What is the next action or deeper link?

Operator content rules

Include Exclude
Problem, outcome, operator actions, limitations, plain-language terms src/ paths, schema field dumps, maturity wave letters as primary content, vendor prompt text, LCDL task IDs, pip install as primary instruction

System page contract

Every system page must include:

  1. Feature ID and status
  2. Intent — what the capability does technically
  3. Behavior — contracts, schemas, catalogs, tools
  4. Limits — maturity honesty, non-goals
  5. Links — canonical deep docs (ADRs, catalogs, wiki overlays)

System content rules

Include Exclude
Architecture, contracts, schemas, catalogs, ADRs, pack authoring, CI Marketing claims; secrets; operational credentials

Granularity rules

Rule Guidance
One capability, one pair Each material capability gets one operator page + one system page (or documented N/A)
Family coverage Related micro-capabilities may share one page when they share one operator workflow (document in feature-index)
Do not duplicate deep docs System pages link to existing ARCHITECTURE.md, NODE-CATALOG.md, wiki/semantic/, etc. — move files only in later phases
Honest maturity Operator pages state user-visible limits; system maturity pages remain source of truth for I1/I2 claims

Structure similarity checklist

Operator and system pages for the same feature_id should mirror section order where possible:

Section Operator System
Intent User problem + outcome Technical intent + contracts
Behavior What happens from operator view Schemas, modules, catalogs
Limits What is not available yet Maturity state, non-goals
Links Next operator steps Deep maintainer docs

Agents and humans should be able to jump between paired pages by feature_id or paired_page frontmatter.

Change contract

Before a material handbook change:

  1. Locate or create the FI-* feature ID in feature-index.md.
  2. Read the paired operator and system pages.
  3. Identify affected concepts, packs, sessions, or ecosystem boundaries.

After the change:

  1. Update the system page when backend behavior, contracts, or maturity change.
  2. Update the operator page when observable platform behavior, workflows, or limitations change.
  3. Update feature-index.md and traceability-matrix.md.
  4. Add or update ADRs when invariants or ownership boundaries change.
  5. Rebuild fiw: python3 generator/build-site.py in forge-intelligence-website.

Do not copy secrets, internal diagnostics, or private operational procedures into operator pages.

Publish rules

Rule Detail
Homepage docs/index.md leads with operator Start here
Maintainer section System handbook + existing deep docs linked secondarily
Demote technical dumps Node catalog, maturity matrices, vendor prompt packs not in primary Start here
Dead links Do not link excluded paths (e.g. registries/*.yaml) from homepage — note repo-only on system pages
Nav order Operator pages: nav_order 1–99; system pages: 100+

Agent findability

  • Use stable FI-* IDs in frontmatter and feature-index rows.
  • Keep glossary.md aligned with operator vocabulary.
  • Pair every operator page with a system page or explicit N/A reason.
  • Session and concept dual-wiki patterns remain documented in DUAL-WIKI.md — operator pages explain what they mean for users; system pages link to implementation.