repo-onboarding-context-map

Repo Onboarding & Context Map

Purpose

Inspect an unfamiliar repo and produce a durable context map so future sessions know the project's structure, commands, protected paths, and risky system boundaries without re-investigating each session.

Named reader: workflows/session-initiation.md step 5 — every new session reads docs/specs/repo-context.md when it exists and is <90 days old, instead of re-investigating. The map header MUST carry Generated: <YYYY-MM-DD> so readers can apply the freshness gate.

When to invoke

• First-time installation of Fusebase Flow into an existing repo
• Operator says "I'm picking up this repo" / "what's in this codebase?" / "set up flow here"
• After a major structural change (large rename, monorepo split, framework swap)
• When docs/specs/repo-context.md is missing or older than 90 days

Do not invoke when

• A current repo-context.md exists and the repo hasn't changed structurally
• Operator is asking a code-specific question — use code-review or normal investigation
• A spec is in flight — don't pivot to onboarding mid-ticket

Required inputs

Input	Where it lives	If missing
Repo root	git root	Stop; ask operator to confirm working directory
Package/project files	package.json, pyproject.toml, Cargo.toml, etc.	Note "no manifest detected"; describe based on file extensions only
Existing READMEs	README.md, docs/, etc.	Note absence; flag as Phase-4 onboarding gap
CLI edition map, for this edition	docs/fusebase-cli-edition.md	Continue with generic repo map, but mark CLI provider asset mapping unknown

Procedure

1. List repo root files (top level only). Identify project type (Node/Python/Go/Rust/etc.) and frontend/backend split if visible.
2. Read root README.md if present. Read up to 3 most-referenced docs in docs/.
3. If this is the Fusebase CLI edition or a downstream Fusebase Apps project, read docs/fusebase-cli-edition.md and record which CLI provider assets are present and relevant.
4. Detect build/test/lint commands from manifest files. Capture exact commands.
5. Identify protected-path candidates: long-lived worker code, generated files, migration files, deployment configs.
6. Identify risky system boundaries: external APIs, database migrations, auth surfaces, file system writes outside repo.
7. Run git log --oneline -30 to read commit cadence + recent areas of activity.
8. Save findings to docs/specs/repo-context.md using templates/spec.md adapted for context-mapping (see template). Stamp a Generated: <YYYY-MM-DD> line in the header — workflows/session-initiation.md step 5 uses it for the 90-day freshness gate.
9. Propose updates to AGENTS.md "project-specific values" section. Show the diff in chat. Do NOT apply unless operator says "apply".
10. Propose initial policies/protected-paths.yml candidates. Save as draft if operator approves; do NOT auto-write.