# Workspace reconnaissance

Use these to understand _what a directory is_ and inventory its contents before
reading anything in depth. All accept `--format json` and `-o <file>`.

## `occ [directories...]` — the root scan

scc-style summary tables for office documents (and, by default, `scc` code metrics).

```bash
occ docs/ reports/                 # tabular metrics grouped by type
occ . --format json                # machine-readable inventory
occ . --structure --format json    # also extract heading trees (RAG-friendly, with char offsets)
occ . --quick                      # file count + size by extension, skip parsing (fast)
```

Useful flags: `-f, --by-file` (row per file), `--include-ext`/`--exclude-ext`,
`--exclude-dir <dirs>` (default `node_modules,.git`), `--no-gitignore`,
`--sort files|name|words|size`, `--token-budget <n>` with `--tokenizer
heuristic|o200k_base|cl100k_base`, `--large-file-limit <mb>` (default 50),
`--no-code` (skip scc), `-o <file>`, `--ci` (ASCII only).

## `occ describe [directories...]`

Quickly classify one or more directories from fast file and manifest signals
(is this a code / office / documentation / data / mixed project?).

```bash
occ describe . --format json
occ describe apps/* --quiet        # summary only
```

Flags: `--full` (full report), `--quiet` (summary only), `--max-projects <n>`
(default 25), `--exclude-dir`, `--no-gitignore`, `-o`.

## `occ workspace describe [rootDir]`

Same classification as `occ describe`, scoped to a single workspace root.

## `occ workspace analyze [rootDir]`

Analyze workspace code, documents, and structures with a versioned JSON contract.
Defaults to `--format json`. This is the one-call snapshot for agents.

```bash
occ workspace analyze . -o ws.json
occ workspace analyze . --no-documents     # code + structures only
```

Flags: `--no-code`, `--no-documents`, `--no-structures`, `--exclude-dir`,
`--large-file-limit <mb>`, `--no-gitignore`, `-o`.

## `occ workspace documents [rootDir]`

Inspect workspace document summaries and cross-document references. Defaults to
`--format json`.

Flags: `--max-files <n>` (default 50), `--max-reference-files <n>` (default 20),
`--include-markdown`, `--exclude-dir`, `-o`.

## Suggested sequence

1. `occ describe . --format json` — what am I looking at?
2. `occ workspace analyze . --format json -o ws.json` — full inventory.
3. Drill into specifics with the code or document commands.
