Lesson 00 — Orientation and repository contract

Outcome

Understand how to use this repository as both a course and a codebase. You will not add product code yet; you will make sure you can explain Forge's purpose, boundaries, vocabulary, and documentation workflow.

Why this comes now

A complex systems project becomes much harder when every coding session starts by rediscovering what the project means. Before code, establish the small set of documents that are allowed to define current truth.

Understand

Forge is a control plane around engineering work. The Task is primary; agent sessions are subordinate. The repository is intentionally layered: short current-truth documents for daily work, ADRs for reasons, research for evidence, and archive for history.

The most important habit is that architecture is allowed to change, but changes must become explicit. We do not keep known-wrong canonical text and expect future humans or agents to apply mental patches.

Build the real project

1. Run bun install, then bun run docs:dev. Use the VitePress site as the main human reading surface.
2. Read docs/start-here.md, docs/context.md, docs/product/PRD.md, and docs/architecture/OVERVIEW.md.
3. In your own words, add a short entry to docs/status/LEARNING_LOG.md answering: “What is Forge, and what is it not?”
4. Initialize Git if this starter is not yet a repository.
5. Make the initial documentation/scaffold commit.
6. Confirm that docs/archive/ is understood as historical input, not authority.

Completion gate

You can explain these distinctions without looking them up: Task vs Agent Run; Agent Adapter vs Execution Environment; current docs vs ADRs vs archive. bun run docs:build succeeds, the Course/Architecture/Research/Status navigation works, and git status is clean after your initial commit.

Pitfalls to avoid

Do not begin “improving” the architecture in Lesson 00. Do not copy the archived schema into code. The point is to establish the contract that makes later change manageable.

References

Required: Forge docs home, Documentation site guide, System overview, VitePress getting started. Optional: Architecture Decision Records by Michael Nygard.

Checkpoint

Set docs/status/CURRENT.md current lesson to 01 and record any genuinely unclear vocabulary as an open question rather than silently inventing a meaning.