@harness-forge/cli 0.1.0

package/docs/manifests.md

@@ -0,0 +1,16 @@
+# Manifest Governance
+
+Harness Forge uses manifests to keep installs, docs, and package surfaces aligned.
+
+## Primary manifests
+
+- `manifests/catalog/index.json` points to bundle, profile, target, and catalog inventories
+- `manifests/catalog/language-assets.json` maps language packs to their surfaced docs and rule entrypoints
+- `manifests/catalog/seeded-knowledge-files.json` provides file-level coverage for the imported starter archives
+- `manifests/catalog/package-surface.json` defines the required published file surface
+
+## Update rules
+
+- add or change seeded files only with a matching update to the seeded coverage manifest
+- keep package surface paths aligned with `package.json` publish configuration
+- do not reference template validators from docs unless the paths are shipped in the package

package/docs/migration/reference-project.md

@@ -0,0 +1,18 @@
+# Migration from the Reference Project
+
+Harness Forge treats migration as an explicit planning step. The migration
+scanner detects reference-project footprints and suggests equivalent bundles
+without silently overwriting unmanaged content.
+
+## What Harness Forge preserves
+
+- root compatibility guidance through `AGENTS.md`
+- hidden agent surfaces such as `.agents/skills/`
+- shipped workflow validators under `scripts/templates/`
+- seeded language knowledge under `knowledge-bases/seeded/`
+
+## What improves over the reference project
+
+- file-level coverage for imported seed archives
+- package-surface validation for hidden target content
+- clearer split between imported seed content and authored product docs

package/docs/observability/benchmark-authoring.md

@@ -0,0 +1,6 @@
+# Benchmark Authoring
+
+Benchmarks should assert more than recommendation IDs.
+
+They can also describe expected repo maps, instruction scopes, observability
+signals, and safe parallelization outcomes for representative fixtures.

package/docs/observability/eval-model.md

@@ -0,0 +1,7 @@
+# Evaluation Model
+
+Harness Forge treats evaluation as local, reproducible evidence rather than
+remote analytics.
+
+Raw events feed derived summaries so maintainers can inspect usefulness, drift,
+and benchmark health from local artifacts alone.

package/docs/observability/event-taxonomy.md

@@ -0,0 +1,12 @@
+# Event Taxonomy
+
+Local observability events should stay typed, append-safe, and useful without
+external telemetry.
+
+Starter categories:
+
+- recommendation decisions
+- flow recovery updates
+- support drift findings
+- benchmark outcomes
+- parallel execution status changes

package/docs/observability.md

@@ -0,0 +1,44 @@
+# Observability
+
+Observability in Harness Forge is local-first and diagnostic. It is meant to
+help operators understand whether recommendations, maintenance commands, and
+flow recovery are actually working without sending data to an external service.
+
+## Signals worth tracking
+
+- bundle use
+- skill use
+- hook runs
+- validation failures
+- recommendation acceptance
+- target mix
+- flow recovery checks
+- maintenance command usage
+
+## Runtime surfaces
+
+- `.hforge/observability/effectiveness-signals.json`
+- `.hforge/observability/summary.json`
+- `.hforge/state/install-state.json`
+- `.hforge/runtime/index.json`
+- `node scripts/runtime/report-effectiveness.mjs --json`
+- `hforge observability summarize --json`
+- `hforge observability report . --json`
+- `hforge recommend <repo> --json`
+- `hforge flow status --json`
+- `hforge review --root <repo> --json`
+
+## Design constraints
+
+- no external service is required
+- payloads must stay actionable without backend aggregation
+- privacy-sensitive workspaces should be able to inspect or remove local signal
+  files directly
+
+## What a healthy signal stream looks like
+
+- recommendation runs record accepted or rejected outcomes
+- `doctor` and `audit` runs leave a visible trace
+- `init` and `refresh` runs update the visible runtime version metadata
+- flow recovery records the active feature and stage
+- signal summaries can be inspected locally before release or handoff

package/docs/pack-authoring.md

@@ -0,0 +1,19 @@
+# Pack Authoring
+
+Use this guide when adding a new language or capability pack.
+
+## Minimum content for a first-class language pack
+
+- language overview
+- review checklist or equivalent review guidance
+- framework notes where relevant
+- at least one scenario example
+- coding style, patterns, testing, security, and hooks guidance
+
+## Seeded pack workflow
+
+1. import or author the canonical pack content
+2. map every shipped file in `manifests/catalog/seeded-knowledge-files.json`
+3. add the knowledge base path to bundle manifests
+4. add catalog and rules entry docs
+5. run `npm run validate:release`

package/docs/parallel-worktrees.md

@@ -0,0 +1,6 @@
+# Parallel Worktrees
+
+Harness Forge plans parallel execution conservatively.
+
+The generated plan should make shard ownership, validation gates, merge
+criteria, and fallback-to-single-thread reasons obvious before work starts.

package/docs/profile-guide.md

@@ -0,0 +1,63 @@
+# Profile Guide
+
+Profiles are behavioral overlays that change how Harness Forge recommends,
+installs, validates, and recovers work. A real profile does more than label a
+bundle set: it changes skill emphasis, validation strictness, review depth, and
+risk posture.
+
+## What a profile controls
+
+- default bundles and capabilities
+- preferred skills
+- recommended hooks
+- validation strictness
+- review depth
+- risk posture
+- target compatibility
+
+## Shipped profiles
+
+| Profile | Primary use | Validation | Review | Risk posture |
+| --- | --- | --- | --- | --- |
+| `core` | smallest portable install | standard | standard | balanced |
+| `developer` | day-to-day implementation | standard | standard | balanced |
+| `reviewer` | correctness and compatibility review | strict | deep | low |
+| `security` | trust boundaries and sensitive services | strict | deep | low |
+| `release-manager` | release and package safety | strict | deep | low |
+| `rapid-prototyping` | fast iteration | lenient | shallow | aggressive |
+| `legacy-modernization` | incremental cleanup of older repos | strict | deep | low |
+| `research-first` | decision-heavy discovery work | standard | deep | balanced |
+| `game-dev-native` | native and scripting-heavy game loops | standard | standard | balanced |
+| `ai-runtime` | orchestration, evaluation, and agent runtime work | strict | deep | balanced |
+
+## Practical guidance
+
+- use `core` when you need the smallest durable baseline
+- use `developer` for routine implementation with repo intelligence and flow
+  recovery
+- use `reviewer`, `security`, or `release-manager` when correctness and safety
+  dominate
+- use `legacy-modernization` or `research-first` when discovery is the hard
+  part
+- use `rapid-prototyping` only when speed matters more than deep validation
+
+## Interactive setup depth
+
+The interactive CLI exposes operator-facing setup depth as:
+
+| Interactive setup depth | Backing manifest profile | Intent |
+| --- | --- | --- |
+| `quick` | `core` | Smallest guided baseline with review-before-write safety |
+| `recommended` | `developer` | Best default for most repos and day-to-day work |
+| `advanced` | `ai-runtime` | Deep runtime setup with optional modules and broader AI-layer features |
+
+Optional modules in advanced setup include working memory, task-pack support,
+decision templates, export support, and recursive runtime. These modules
+change what the CLI highlights during setup and what runtime surfaces it keeps
+easy to reach after initialization.
+
+## Machine-readable source of truth
+
+Profile manifests live under `manifests/profiles/*.json`. Each profile declares
+bundle ids, preferred skills, recommended hooks, and target compatibility so
+recommendations and validation surfaces can stay aligned.

package/docs/quality-gates.md

@@ -0,0 +1,56 @@
+# Quality Gates
+
+Interactive CLI changes are protected by dedicated contract and integration
+coverage for:
+
+- no-argument onboarding entry
+- project-hub routing in initialized repos
+- non-interactive and CI-safe fallback behavior
+- no-color and narrow-terminal rendering
+- direct `init --agent ... --yes|--dry-run` compatibility
+
+Harness Forge quality gates should reject shallow or misleading product
+surfaces, not only broken JSON.
+
+## Daily maintainer gate
+
+Run `npm run validate:local` before opening or updating a PR.
+
+That path proves:
+
+- the project still builds
+- tests pass
+- the packed install surface is still valid
+- docs and commands still match
+- runtime/manifests still line up
+
+## Release gate
+
+Run `npm run validate:release` or `npm run release:dry-run` before publish.
+
+That path adds:
+
+- CLI smoke execution through the built package entrypoint
+- template and content validation
+- package-surface verification
+- PowerShell workflow checks where available
+- release-oriented command/help checks
+
+## Gate families
+
+- release smoke
+- CLI smoke
+- content metadata validation
+- seeded knowledge coverage
+- generated sync validation
+- package-surface validation
+- benchmark recommendation checks
+- docs and command alignment
+
+## What the gates should prove
+
+- no placeholder-grade docs or skills ship as "complete"
+- framework coverage matches recommendation logic
+- docs and commands stay aligned
+- package manifests match runtime behavior
+- release candidates are package-safe before publish

package/docs/quickstart.md

@@ -0,0 +1,41 @@
+# Quickstart
+
+```bash
+npx @harness-forge/cli
+npx @harness-forge/cli shell setup --yes
+npx @harness-forge/cli init --root . --agent codex --setup-profile recommended --yes
+npx @harness-forge/cli init --root . --agent codex --dry-run
+npx @harness-forge/cli bootstrap --root .
+npx @harness-forge/cli init --root . --json
+hforge commands --json
+npm run validate:release
+```
+
+## Source checkout flow for maintainers
+
+```bash
+npm install
+npm run build
+node dist/cli/index.js catalog --json
+node dist/cli/index.js init --root . --json
+node dist/cli/index.js install --target codex --lang typescript --with workflow-quality --dry-run
+node dist/cli/index.js refresh --root .
+node dist/cli/index.js review --root . --json
+node dist/cli/index.js recommend tests/fixtures/benchmarks/typescript-web-app --json
+npm run validate:local
+npm run validate:release
+```
+
+## Flow
+
+1. use published `npx` when you want zero-build bootstrap into a repo
+2. run `shell setup` once if you want bare `hforge` on PATH without a global install
+3. use the no-argument interactive flow when you want guided folder, target,
+   setup-profile, and review behavior
+4. use direct `init --agent ... --yes` when you need automation-safe setup
+5. build from source only when you are developing Harness Forge itself
+6. choose a target (`claude-code` or `codex`)
+7. preview the install plan for the language and capability bundles you need
+8. inspect an existing repository with `recommend` when the right pack is not obvious
+9. use `refresh`, `task`, `pack`, `review`, and `export` to inspect the hidden runtime once work is in flight
+10. use `.specify/` and the promoted skills for real work

package/docs/release-process.md

@@ -0,0 +1,30 @@
+# Release Process
+
+## Release stages
+
+1. Prepare the branch and update user-facing docs.
+2. Run `npm run validate:local`.
+3. Run `npm run release:dry-run`.
+4. Review `CHANGELOG.md` and release notes scope.
+5. Tag the release and let GitHub Actions run the publish workflow.
+
+## Required checks
+
+- `npm run build`
+- `npm test`
+- `npm run validate:package-surface`
+- `npm run validate:doc-command-alignment`
+- `npm run validate:runtime-consistency`
+- `npm run validate:release`
+
+## Publish posture
+
+- the package is published from GitHub Actions, not an ad hoc local shell
+- release validation must complete before `npm publish`
+- the workflow should leave a packed artifact and a traceable release record
+
+## Post-release verification
+
+- confirm `npx @harness-forge/cli --help` works
+- confirm `npx @harness-forge/cli init --root . --json` works in a clean temp repo
+- confirm the published tarball still contains the expected docs, manifests, schemas, and target payloads

package/docs/repo-cartography.md

@@ -0,0 +1,12 @@
+# Repo Cartography
+
+Harness Forge uses repo cartography to separate observed repository facts from
+instruction recommendations.
+
+Current scaffolded surfaces:
+
+- `node scripts/intelligence/cartograph-repo.mjs <repo> --json`
+- `node scripts/intelligence/classify-boundaries.mjs <repo> --json`
+- `node scripts/intelligence/synthesize-instructions.mjs <repo> --dry-run --json`
+
+The contract-backed output is designed to stay inspectable and conservative.

package/docs/style-guides/agent-style-guide.md

@@ -0,0 +1,21 @@
+---
+id: style-guide-agent
+kind: style-guide
+title: Agent Documentation Style Guide
+summary: Shared expectations for documenting agent responsibilities and escalation behavior.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - all
+generated: false
+---
+# Agent Documentation Style Guide
+
+- define mission first
+- list required inputs
+- outline workflow or process
+- describe output contract
+- define stop conditions and escalation rules

package/docs/style-guides/command-style-guide.md

@@ -0,0 +1,21 @@
+---
+id: style-guide-command
+kind: style-guide
+title: Command Documentation Style Guide
+summary: Shared expectations for documenting commands and operational flows.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - all
+generated: false
+---
+# Command Documentation Style Guide
+
+- include syntax or invocation path
+- describe output contract
+- describe side effects
+- describe failure behavior
+- link to shipped validators or manifests when the command depends on them

package/docs/style-guides/rule-style-guide.md

@@ -0,0 +1,20 @@
+---
+id: style-guide-rule
+kind: style-guide
+title: Rule Documentation Style Guide
+summary: Shared expectations for documenting shared and language-specific rule packs.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - all
+generated: false
+---
+# Rule Documentation Style Guide
+
+- identify the language or shared layer
+- distinguish baseline rules from language-specific rules
+- link back to seeded source content when a rule is imported
+- keep framework-heavy guidance separated from stable baseline rules

package/docs/target-support-matrix.md

@@ -0,0 +1,73 @@
+# Target Support Matrix
+
+Harness Forge keeps one canonical target-capability truth source in
+`manifests/catalog/harness-capability-matrix.json`. The broader
+`manifests/catalog/compatibility-matrix.json` remains a derived view for
+cross-surface relationships.
+
+## Support levels
+
+- `full`: shipped and validated in this package
+- `partial`: usable with explicit gaps and fallback guidance
+- `emulated`: approximated behavior without a native runtime surface
+- `unsupported`: do not rely on it
+
+## Support modes
+
+- `native`: first-class runtime support ships in the package
+- `translated`: support works through portable scripts or guidance layers
+- `emulated`: behavior is approximated rather than native
+- `documentation-only`: only docs and manifests are portable
+- `unsupported`: no packaged runtime support is claimed
+
+## Target summary
+
+| Target | Overall support | Strengths | Gaps |
+| --- | --- | --- | --- |
+| `codex` | full | Templates and docs, Workflow validation, Repo intelligence, Flow orchestration, Maintenance commands, Local observability | Typed hooks |
+| `claude-code` | full | Templates and docs, Workflow validation, Repo intelligence, Flow orchestration, Typed hooks, Maintenance commands, Local observability | none |
+| `cursor` | partial | none | Templates and docs, Workflow validation, Repo intelligence, Flow orchestration, Typed hooks, Maintenance commands, Local observability |
+| `opencode` | partial | none | Templates and docs, Workflow validation, Repo intelligence, Flow orchestration, Typed hooks, Maintenance commands, Local observability |
+
+## Capability honesty
+
+| Capability | Codex | Claude Code | Cursor | OpenCode |
+| --- | --- | --- | --- | --- |
+| Templates and docs | full (native) | full (native) | partial (documentation-only) | partial (documentation-only) |
+| Workflow validation | full (native) | full (native) | partial (documentation-only) | partial (documentation-only) |
+| Repo intelligence | full (native) | full (native) | partial (translated) | partial (translated) |
+| Flow orchestration | full (native) | full (native) | unsupported (unsupported) | unsupported (unsupported) |
+| Typed hooks | partial (documentation-only) | full (native) | unsupported (unsupported) | unsupported (unsupported) |
+| Maintenance commands | full (native) | full (native) | partial (documentation-only) | partial (documentation-only) |
+| Local observability | full (native) | full (native) | partial (documentation-only) | partial (documentation-only) |
+
+## Degraded support details
+
+### Codex
+
+- Typed hooks: partial via documentation-only. Fallback: Use the docs and packaged hook manifests as references, then wire execution manually in the Codex target. Codex ships hook authoring guidance, but not the same native runtime hook model as Claude Code.
+
+### Claude Code
+
+- none
+
+### Cursor
+
+- Templates and docs: partial via documentation-only. Fallback: Use generated docs and manifests as the support surface instead of expecting a native Cursor runtime install. Cursor can consume packaged docs and portable guidance, but not a first-class runtime mapping.
+- Workflow validation: partial via documentation-only. Fallback: Run the validators from the repository rather than relying on a Cursor-specific runtime integration. Validation guidance is portable, but no Cursor-native runtime wiring is shipped.
+- Repo intelligence: partial via translated. Fallback: Inspect `.hforge/runtime/index.json` and `.hforge/library/`, then run the intelligence scripts directly and treat the output as operator guidance. Repo intelligence is available as thin bridges, portable scripts, and generated hidden `.hforge/` state rather than a native Cursor runtime surface.
+- Flow orchestration: unsupported via unsupported. Fallback: Do not rely on packaged flow recovery for Cursor; use `.hforge/runtime/index.json` and the thin bridge surfaces only. No first-class Cursor flow-state recovery surface is shipped beyond the hidden `.hforge/` runtime summary and bridge surfaces.
+- Typed hooks: unsupported via unsupported. Fallback: Use hook docs as references only; do not claim native Cursor hook execution. Cursor does not have a packaged native hook runtime in this repository.
+- Maintenance commands: partial via documentation-only. Fallback: Run the maintenance commands from the repository rather than expecting Cursor-specific runtime integration. Maintenance guidance is portable, but a Cursor-native runtime surface is not shipped.
+- Local observability: partial via documentation-only. Fallback: Inspect the local observability artifacts directly from the repository. Observability artifacts are portable, but no native Cursor runtime surface is shipped.
+
+### OpenCode
+
+- Templates and docs: partial via documentation-only. Fallback: Use generated docs and manifests as the support surface instead of expecting a native OpenCode runtime install. OpenCode can consume packaged docs and portable guidance, but not a first-class runtime mapping.
+- Workflow validation: partial via documentation-only. Fallback: Run the validators from the repository rather than relying on an OpenCode-specific runtime integration. Validation guidance is portable, but no OpenCode-native runtime wiring is shipped.
+- Repo intelligence: partial via translated. Fallback: Inspect `.hforge/runtime/index.json` and `.hforge/library/`, then run the intelligence scripts directly and treat the output as operator guidance. Repo intelligence is available as thin bridges, portable scripts, and generated hidden `.hforge/` state rather than a native OpenCode runtime surface.
+- Flow orchestration: unsupported via unsupported. Fallback: Do not rely on packaged flow recovery for OpenCode; use `.hforge/runtime/index.json` and the thin bridge surfaces only. No first-class OpenCode flow-state recovery surface is shipped beyond the hidden `.hforge/` runtime summary and bridge surfaces.
+- Typed hooks: unsupported via unsupported. Fallback: Use hook docs as references only; do not claim native OpenCode hook execution. OpenCode does not have a packaged native hook runtime in this repository.
+- Maintenance commands: partial via documentation-only. Fallback: Run the maintenance commands from the repository rather than expecting OpenCode-specific runtime integration. Maintenance guidance is portable, but an OpenCode-native runtime surface is not shipped.
+- Local observability: partial via documentation-only. Fallback: Inspect the local observability artifacts directly from the repository. Observability artifacts are portable, but no native OpenCode runtime surface is shipped.
+

package/docs/targets/capability-families.md

@@ -0,0 +1,13 @@
+# Capability Families
+
+Harness Forge groups target support into a small set of capability families so
+support claims stay explicit instead of implied.
+
+- authoring: templates, docs, and workflow validation
+- intelligence: repo scanning and recommendation output
+- orchestration: flow status and recovery
+- automation: typed hooks and related runtime behavior
+- operations: maintenance commands and local observability
+
+Canonical target-capability truth lives in
+`manifests/catalog/harness-capability-matrix.json`.

package/docs/targets/translation-vs-emulation.md

@@ -0,0 +1,11 @@
+# Translation vs Emulation
+
+Harness Forge distinguishes between support that is:
+
+- `native`: the target ships a first-class runtime surface
+- `translated`: portable scripts or guidance can bridge the gap
+- `emulated`: behavior can be approximated, but not natively
+- `documentation-only`: only docs and manifests are portable
+
+Use these labels when describing degraded target support so operators know what
+kind of fallback they are relying on.

package/docs/targets.md

@@ -0,0 +1,20 @@
+# Targets
+
+Harness Forge emphasizes Codex and Claude Code with project-owned runtime
+surfaces in `.codex/` and `.claude/`.
+
+## First-class targets
+
+- `codex` for the strongest local runtime, recommendation, and maintenance path
+- `claude-code` for first-class hook support plus the shared hidden `.hforge/` runtime
+
+## Portable targets
+
+- `cursor` for docs, manifests, and recommendation portability
+- `opencode` for docs, manifests, and recommendation portability
+
+## Production note
+
+No target should expose the canonical AI layer at the repo root. Installed
+canonical skills, rules, knowledge, templates, runtime state, and memory stay
+under `.hforge/`, while root and target-specific files act as thin bridges.

package/docs/templates/authoring.md

@@ -0,0 +1,23 @@
+# Template Authoring Guide
+
+Author task and workflow templates in Markdown with YAML front matter.
+
+- keep required metadata fields present
+- keep required sections in order
+- reference shipped validator scripts when a validation step is required
+- prefer paths under `scripts/templates/` and never point to private local-only
+  validators
+- validate with both shell and PowerShell scripts when cross-platform support
+  matters
+
+## Shipped validator bundle
+
+- `scripts/templates/shell/check-template-frontmatter.sh`
+- `scripts/templates/shell/check-template-links.sh`
+- `scripts/templates/shell/list-missing-template-sections.sh`
+- `scripts/templates/shell/verify-workflow-contracts.sh`
+- `scripts/templates/powershell/Check-TemplateFrontmatter.ps1`
+- `scripts/templates/powershell/Check-TemplateLinks.ps1`
+- `scripts/templates/powershell/Get-MissingTemplateSections.ps1`
+- `scripts/templates/powershell/Test-WorkflowContracts.ps1`
+- `scripts/templates/config/required-sections.json`

package/docs/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+## Interactive CLI issues
+
+- if `hforge` is run without arguments in CI or another non-TTY environment,
+  the CLI will not prompt; rerun with explicit flags such as
+  `hforge init --root <repo> --agent codex --yes` or `--dry-run`
+- if the no-argument CLI opens onboarding when you expected the project hub,
+  verify that `.hforge/runtime/index.json` exists in the repo root
+- if the onboarding flow is interrupted before confirmation, no writes should
+  occur; if a write was partially applied later in the flow, use `doctor`,
+  `audit`, or `refresh` to inspect the runtime state
+- if path selection or target selection looks wrong, rerun the setup and
+  override the recommended defaults explicitly
+
+## Node runtime issues
+
+- confirm Node.js 22+ is available on the PATH
+- if bare `hforge` is not found after setup, run `npx @harness-forge/cli shell status --json`
+  or use the workspace-local launcher under `.hforge/generated/bin/`
+- rebuild with `npm run build` before using `install.sh` or `install.ps1`
+- run `hforge --help` to confirm the built entrypoint still starts cleanly
+
+## Missing seeded language content
+
+- run `npm run validate:seeded-coverage`
+- inspect `manifests/catalog/seeded-knowledge-files.json`
+- confirm the missing file still exists under `knowledge-bases/seeded/`
+
+## Missing validator bundle files
+
+- run `npm run validate:package-surface`
+- confirm `scripts/templates/README.md` and the script/config files are present
+- run `npm run release:dry-run` if the problem appears only in publish validation
+
+## Target install surprises
+
+- use `--dry-run` first to preview copy and merge behavior
+- inspect `targets/<target>/adapter.json` for path mapping behavior
+- confirm the target supports the capability you are installing
+
+## Init or runtime drift
+
+- run `hforge init --root <repo> --json` to re-establish the base runtime files
+- run `hforge refresh --root <repo>` after install changes to rewrite shared runtime summaries
+- run `hforge doctor --root <repo>` to see missing managed paths and stale task artifacts
+- run `hforge audit --root <repo>` for a fuller package and runtime report
+
+## Command-surface mismatches
+
+- run `npm run validate:doc-command-alignment`
+- compare `docs/commands.md` with `hforge commands --json`
+- confirm the built CLI in `dist/cli/index.js` is current

package/docs/versioning-and-migration.md

@@ -0,0 +1,25 @@
+# Versioning and Migration
+
+Harness Forge versions both its runtime code and its shipped content surface.
+
+## Runtime version surfaces
+
+- `package.json` provides the published package version
+- `.hforge/state/install-state.json` records the installed package version and runtime schema version
+- `.hforge/runtime/index.json` records the runtime schema version and generated package version
+- `hforge status --root <repo>` surfaces both values to operators
+
+## What changes must be treated carefully
+
+- bundle manifest IDs and paths
+- root compatibility files like `AGENTS.md`
+- seeded knowledge-pack paths under `knowledge-bases/seeded/`
+- validator bundle paths referenced by templates and docs
+
+## Migration guidance
+
+- use the reference-project guide before renaming or relocating shipped content
+- preserve canonical seeded paths unless a manifest declares a transformed
+  destination
+- refresh the runtime with `hforge refresh --root <repo>` after layout changes
+- run `npm run validate:release` after any package-surface change

package/examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+Harness Forge examples currently focus on the shipped seeded language packs.
+
+## Seeded scenario indexes
+
+- `examples/knowledge-bases/README.md`
+- `knowledge-bases/seeded/typescript/examples/`
+- `knowledge-bases/seeded/java/examples/`
+- `knowledge-bases/seeded/dotnet/examples/`
+- `knowledge-bases/seeded/lua/examples/`
+- `knowledge-bases/seeded/powershell/examples/`