# Workspace Map

## Important Folders

- `modules/`: pluggable onboarding modules. Each module has metadata, steps, knowledge, and FAQ.
- `sources/`: source evidence, manifest, extracted text, table exports, image notes, and external link notes.
- `assets/`: downloaded binary originals for PDFs, images, and videos.
- `search/`: generated full-text index.
- `skills/onboarding-buddy/`: local Codex skill.
- `state-template/`: learner runtime state schema.
- `scripts/`: deterministic maintenance, ingestion, indexing, search, validation, and install tools.
- `.ai/context/`: six-layer durable context for future agents.

## Important Files

- `AGENTS.md`: global operating contract.
- `AGENT_COMPATIBILITY.md`: cross-agent compatibility map for Codex, Claude, Cursor, Copilot, Gemini, and Cline.
- `BOOTSTRAP.md`: first-run package bootstrap prompt for a new agent session.
- `bootstrap.ps1`: optional Windows bootstrap that detects Python, asks before installing uv, and runs kit verification/search with local or uv-managed Python.
- `bootstrap.sh`: optional macOS/Linux bootstrap that detects Python, asks before installing uv, and runs kit verification/search with local or uv-managed Python.
- `CLAUDE.md`: Claude Code adapter.
- `GEMINI.md`: Gemini adapter.
- `HANDOFF.md`: orientation for future maintainers and their Codex.
- `MAINTAINERS.md`: CRUD/read-scope/verification/packaging contract.
- `.github/copilot-instructions.md`: GitHub Copilot adapter.
- `.cursor/rules/onboarding-kit.mdc`: Cursor adapter.
- `.clinerules`: Cline adapter.
- `kit.yaml`: kit metadata, journeys, module order, search paths.
- `start.prompt.md`: startup prompt and learner initialization wording.
- `install.md`: direct and skill-install instructions.
- `sources/source-manifest.yaml`: inventory of all source materials and extraction status.
- `sources/README.md`: source maintenance rules.
- `search/chunks.jsonl`: generated searchable chunks.
- `search/index.json`: generated inverted index.

## Commands

Validate:

```bash
python3 scripts/validate_kit.py
```

First-run package bootstrap:

```bash
sh bootstrap.sh
# or on Windows:
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1

python3 scripts/bootstrap_session.py
```

Ingest Feishu/Lark sources:

```bash
python3 scripts/ingest_lark_sources.py
```

Rebuild search:

```bash
python3 scripts/index_knowledge.py
```

Search:

```bash
python3 scripts/search_knowledge.py "<query>"
python3 scripts/search_knowledge.py "<query>" --module <module-id>
```

Module CRUD:

```bash
python3 scripts/module_crud.py list
python3 scripts/module_crud.py show day1-landing
python3 scripts/module_crud.py create <module-id> --title "<title>" --owner "<owner>"
python3 scripts/module_crud.py disable <module-id>
```

Skill install:

```bash
python3 scripts/install_skill.py --dry-run
python3 scripts/install_skill.py
python3 scripts/install_skill.py --force
```

Package:

```bash
python3 scripts/package_kit.py
```

## Current Source Inventory

As of the 2026-07-01 ingestion:

- 23 manifest items.
- 6 linked document references.
- 1 embedded sheet.
- 2 media resources.
- 7 images.
- 4 external links.
- 1 sanitized manual note for learning-zone, account registration, channel publishing, and PPL boundary details.
- Search index was later rebuilt to include cross-agent adapters and manual source updates.

Known partial sources:

- `实习生学习专区 - 决胜`: metadata only because the current Feishu user lacks permission.
- `实习生PPL`: metadata only because it is a bitable, not a docx document.
- `实习生清单`: metadata only because it is a sheet, not a docx document.

## External Systems

- Feishu/Lark docs and wiki via `lark-cli docs +fetch`.
- Feishu/Lark media via `lark-cli docs +media-download`.
- Feishu/Lark sheets via `lark-cli sheets +cells-get`.
- Public external links are best-effort and may return metadata-only text.

## Inspection Paths

- Onboarding behavior: `AGENTS.md`, `start.prompt.md`, `skills/onboarding-buddy/SKILL.md`.
- New maintainer handoff: `HANDOFF.md`, then `MAINTAINERS.md`, then `.ai/context/README.md`.
- New agent session full package warmup: `BOOTSTRAP.md`, Python/uv detection through `bootstrap.ps1` or `bootstrap.sh` when needed, then `scripts/bootstrap_session.py`, then `.ai/context/session-bootstrap.md`.
- Cross-agent adapter issue: `AGENT_COMPATIBILITY.md`, then the relevant thin adapter file.
- Journey or order issue: `kit.yaml`.
- Module issue: `modules/<module-id>/module.yaml` and `steps.yaml`.
- FAQ or answer issue: `modules/<module-id>/faq.yaml`, `knowledge.md`, then search results.
- Source issue: `sources/source-manifest.yaml`, `sources/README.md`, matching `sources/*` file, matching `assets/*` file.
- Maintenance issue: `MAINTAINERS.md`, then relevant script.
- Resume or architecture issue: `.ai/context/04-state-ledger.md`.
