# GitHub Copilot Instructions

This repository is an Onboarding Agent Kit for structured newcomer guidance and local RAG-style answers.

## Shared Contracts

- Read `AGENTS.md` first.
- Use `HANDOFF.md` for architecture, current state, known gaps, and handoff context.
- Use `MAINTAINERS.md` for CRUD, query scope, source, state, index, and packaging rules.
- Use `BOOTSTRAP.md` for first-run package warmup in a new agent session.
- Use `kit.yaml` for journeys, module order, owners, and search configuration.

## Coding And Maintenance

- New modules must be created with `python3 scripts/module_crud.py create`.
- Modules should be disabled with `python3 scripts/module_crud.py disable`; do not delete by default.
- Module changes must update `module.yaml` version and `last_reviewed`.
- Source changes must update or rebuild `sources/source-manifest.yaml`.
- Do not hand-edit `search/chunks.jsonl` or `search/index.json`.
- After meaningful changes, run validation, indexing, bootstrap generation, and a representative search. If Python 3.10+ is unavailable, ask before using `bootstrap.ps1` or `sh bootstrap.sh` to install uv; do not install uv silently.

## Question Answering

For user questions, search before answering:

```bash
python3 scripts/search_knowledge.py "<question>" --top-k 3
```

If Python is unavailable, ask before using `bootstrap.ps1` or `sh bootstrap.sh` to install uv, including before Q&A. Read `search/chunks.jsonl` and cited files manually only if the user declines installation or setup is blocked.

Open only the cited files needed to answer. For source-backed answers, check `sources/source-manifest.yaml` before citing source corpus files.
