compass
=======

Small scripts for rapidly orienting in a project area.

Each script is standalone:
run individually for debugging,
or compose into larger summaries (e.g. an agent's system prompt).

## Conventions

- One concern per script.
- Output is markdown, scoped so the top-level output fits under an `h3` or smaller.
  Composers wrap in larger sections as needed.
- If a script has nothing applicable to say, it stays silent (exits 0 with no output).
  Errors are different: surface those.
- Bash for now.  Nushell on the table once we want to pass structured data between scripts.

## Scripts

- `orient-cwd`        -- describes the current working directory.
- `orient-git`        -- describes the surrounding git repo, if any.
- `orient-project`    -- inlines root orientation docs and detects a meta repo.
- `orient-entrypoints` -- detects entrypoint systems (Makefile etc.) and lists their targets.
- `skim-makefile`     -- summarizes a Makefile's targets as a bullet list.
- `summarize-md-toc`  -- emits a markdown file's heading structure as a bullet list.

Scripts share verb-prefix conventions (`orient-*`, `summarize-*`, ...)
so they tab-complete as groups
when you remember the kind of thing you want but not the specific name.