feat(cli): typed subcommand stubs (Phase 0 + skeleton)

[codewizdave]

Summary

Three commits that land the CLI's design contract and its Phase 0 implementation, in order:

1. docs/cli/*: the architecture documents (02-design.md, 03-architecture.md, 04-corpus.md, 05-testing.md, 06-roadmap.md, plus per-subcommand specs under commands/).
2. apps/cli/* scaffold: @deessejs/package-cli workspace that builds, lints, type-checks, and exposes the bin.
3. Typed subcommand stubs: every one of the six subcommands is wired with commander, parses its args, validates them, and exits 2 with a clear not implemented yet InternalError.

This PR is independent of any other open PR. It branches directly off origin/staging and contains everything needed for the CI to go green on its own.

Why a single PR

The user instruction was that documentation and implementation belong in the same PR. The doc in docs/cli/ is the contract that apps/cli/ must satisfy; splitting them across PRs lets one drift from the other.

What's added

docs/cli/
├── README.md              # vision, audience, success criteria, status
├── 02-design.md           # six subcommands, output conventions, .docs.md format
├── 03-architecture.md     # modules, types, data flow, argv, error model
├── 04-corpus.md           # options A/B/C, decision for B
├── 05-testing.md          # unit + integration + smoke, fixtures
├── 06-roadmap.md          # six phases with exit criteria
└── commands/
    ├── README.md          # per-command index
    ├── ls.md
    ├── cat.md
    ├── grep.md
    ├── find.md
    ├── path.md
    └── symbols.md

apps/cli/
├── package.json           # @deessejs/package-cli, bin, exports, scripts
├── tsconfig.json          # noEmit, NodeNext, types:[node]
├── tsconfig.build.json    # emits dist/, excludes tests
├── eslint.config.js       # flat config
├── vitest.config.ts       # globalSetup rebuilds before tests
├── .gitignore
├── bin/package-cli.mjs    # shebang + import('../dist/index.js')
├── scripts/postbuild.mjs  # chmod 755 on bin
├── src/
│   ├── index.ts           # shebang entry, delegates to cli.run
│   ├── cli.ts             # buildProgram(), run(argv)
│   ├── errors.ts          # ExitCode, UserError, InternalError, exitWithError
│   ├── output.ts          # writeRecords, writeWarning
│   ├── corpus.ts          # DocsFile, Corpus types; loadCorpus, resolveCorpusRoot stubs
│   ├── commands/
│   │   ├── shared.ts      # SubcommandRegist, CommandContext
│   │   ├── ls.ts
│   │   ├── cat.ts
│   │   ├── grep.ts
│   │   ├── find.ts
│   │   ├── path.ts
│   │   └── symbols.ts
│   └── index/
│       ├── build.ts       # buildIndex stub, reportDuplicateSymbol helper
│       └── search.ts      # SymbolMatch, TextMatch types; findSymbols/grepCorpus/listSymbols stubs
└── tests/
    ├── global-setup.ts    # tsc -p tsconfig.build.json before tests
    ├── commands.test.ts   # integration per subcommand (12 tests)
    ├── errors.test.ts     # exit codes and error format (5 tests)
    └── output.test.ts     # writeRecords, writeWarning (5 tests)
```

## Behaviour after this PR

```bash
$ package-cli --version
0.0.0

$ package-cli docs ls /
[error] ls is not implemented yet
exit 2

$ package-cli docs ls
error: missing required argument 'path'
exit 1

$ package-cli docs cat Buffer
[error] cat is not implemented yet
exit 2

$ package-cli docs symbols
[error] symbols is not implemented yet
exit 2

$ package-cli docs symbols extra
error: too many arguments for 'symbols'. Expected 0 arguments but got 1.
exit 1

$ package-cli --corpus /tmp/x docs symbols
[error] symbols is not implemented yet
exit 2
```

Exit codes follow the contract from `docs/cli/02-design.md#exit-codes` and `docs/cli/03-architecture.md#error-model`: 0 success, 1 user error (commander rejects invalid args), 2 internal error (subcommand stub throws `InternalError`).

## Verification

```
pnpm install
pnpm --filter @deessejs/package-cli type-check  # clean
pnpm --filter @deessejs/package-cli lint        # clean
pnpm --filter @deessejs/package-cli build       # builds dist/
pnpm --filter @deessejs/package-cli test:run    # 22 passed

vale --config .vale.ini docs/cli/               # 0 errors
prettier --check docs/cli/** apps/cli/**        # clean
```

## Subsequent phases

Per `docs/cli/06-roadmap.md`:

1. Phase 1: corpus loader (`loadCorpus()` in `src/corpus.ts`, frontmatter validation)
2. Phase 2: read commands (`ls`, `cat`, `path` go from stub to real behavior)
3. Phase 3: indexer and search (`find`, `grep`, `symbols` plus `src/index/{build,search}.ts`)
4. Phase 4: polish (--help, smoke test, changeset)
5. Phase 5: publish

Each phase will be its own PR off `staging`. The doc may grow alongside the implementation when reality forces a correction; a PR that diverges from `docs/cli/` lands **with** an update to the relevant section.

## Changeset

No changeset. Per `CONTRIBUTING.md`: a changeset is only added when a change should cut a release. This PR ships the `0.0.0` placeholder; the first real release lands with Phase 5.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[github-actions]

Coverage Report for @deessejs/example coverage (packages/example)

Status	Category	Percentage	Covered / Total
🟢	Lines	100%	1 / 1
🟢	Statements	100%	1 / 1
🟢	Functions	100%	1 / 1
🟢	Branches	100%	0 / 0

File Coverage

No changed files found.

Generated in workflow #83 for commit 9a852a7 by the Vitest Coverage Report Action

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/deessejs/package-template/@deessejs/example@46

pnpm add https://pkg.pr.new/deessejs/package-template/@deessejs/package-cli@46

commit: 9a852a7