# Tasks: enterprise-docs

**Change ID**: enterprise-docs
**Package**: `@suaveplan/docs`
**Target path**: `packages/devtools/docs/docs`

## 1. Scaffold

- [ ] Create `packages/devtools/docs/docs/` per design layout.
- [ ] Add `markdown` catalog key to root `package.json` carrying `glob`,
      `gray-matter`, `remark-parse`, `remark-gfm`, `unified`,
      `unist-util-visit`, `@types/mdast`.
- [ ] Write `package.json` at version `0.1.0` with subpath exports per feature.
- [ ] Write `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`,
      `README.md`.

## 2. Errors

- [ ] Implement `src/errors/errors.ts` with `DOCS_CODES` registry (eight
      codes) and `DocsError extends SuaveplanError<DocsErrorCode>`.
- [ ] Write `src/errors/errors.test.ts` covering registry shape, every code,
      and round-trip through cause chain.

## 3. Observability

- [ ] Implement `src/observability/observability.ts` and
      `observability.types.ts` exposing `createDocsObservability`.
- [ ] Test against `@opentelemetry/api` no-op providers.

## 4. Types

- [ ] Implement `src/types/docs.types.ts` carrying `DocFile`, `DocLink`,
      `DocCategory` (eighteen-category union), `DocGraph`, `DocNode`,
      `DiscoverOptions`, `SearchResult`, `DiscoverOptionsSchema`.

## 5. Parser

- [ ] Implement `src/parser/parse.ts` using typed mdast traversal, no `as any`,
      timing instrumented via observability.
- [ ] Write `src/parser/parse.test.ts` covering title extraction, frontmatter,
      link extraction, GFM tables, ID stability, category derivation across
      all eighteen genesis categories, root tier, and PARSE_FAILED branch.

## 6. Discovery

- [ ] Implement `src/discovery/discover.ts`: Zod-validate options,
      `AbortSignal` propagation, per-file IO error counter, glob error wrap.
- [ ] Write `src/discovery/discover.test.ts` covering happy path, includeApps,
      ignore, sorting, abort, invalid options, IO error surfacing.

## 7. Graph

- [ ] Implement `src/graph/build-graph.ts` and `src/graph/find-orphans.ts`.
- [ ] Write tests covering link resolution, anchor + external link rejection,
      fragment handling, fuzzy basename match, self-link skip, orphan
      detection, and findOrphans suggestedParent.

## 8. Hierarchy

- [ ] Implement `src/hierarchy/build-hierarchy.ts` with configurable
      `maxDepth`.
- [ ] Write tests covering nesting, category grouping, circular safety, sort
      order, and `HIERARCHY_CYCLE_LIMIT` (when maxDepth=0).

## 9. Search

- [ ] Implement `src/search/search.ts` with timing + counter instrumentation
      and `DOCS.SEARCH_INVALID_QUERY` on non-string input.
- [ ] Write tests covering scoring, snippets, limit, sort, case insensitivity.

## 10. Barrel + subpath exports

- [ ] Author `src/index.ts` with explicit named re-exports — never `export *`.
- [ ] Confirm `package.json` `exports` map has one subpath per feature.

## 11. Docs

- [ ] Sibling `.md` for every `.ts` (excl. `index.ts`, `.test.ts`,
      `.types.ts`). Each ≥200 words across six required sections.
- [ ] `README.md` with Purpose, Install, Quick Start, Modules.

## 12. Gate

- [ ] `bunx turbo lint typecheck test build --filter=@suaveplan/docs` green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/docs` at 100/100/100/100.
- [ ] Banned-pattern scan clean.
- [ ] Test-runner import scan clean.
- [ ] MANIFEST refreshed via `bun scripts/folder-reorg/generate-manifest.ts`.

## 13. Archive

- [ ] Fold `specs/docs/spec.md` into `openspec/specs/docs/spec.md`.
- [ ] Move change folder to `openspec/archive/2026-05-25-enterprise-docs/`.
- [ ] Flip STATUS.md row `–` → `✅` with one-line summary; bump counts.