docs: reorganize docs into bgm and status folders

Group the bgm spec cluster under docs/bgm and move dev logs and plans under docs/status, add an overview index, and update cross-references in the docs, README, and source comments.

packages/bgm/src/collect.ts

@@ -11,7 +11,7 @@
  *    their `include` patterns, and assembles the package's parts, surfaces,
  *    and setups.
  *
- * See docs/bgm-format.md for the format's concrete behavior.
+ * See docs/bgm/format.md for the format's concrete behavior.
  */
 import * as path from 'node:path';
 import picomatch from 'picomatch';

packages/bgm/src/parse.ts

@@ -2,7 +2,7 @@
  * Parse raw definition files (yaml/json/toml text) into JSON objects.
  *
  * A def file's document can be either a single JSON object (the root) or a
- * list of objects; both are handled per docs/bgm-format.md §3. In list mode,
+ * list of objects; both are handled per docs/bgm/format.md §3. In list mode,
  * each object is a separate definition.
  */
 import * as fs from 'node:fs';

packages/bgm/src/schemas.ts

@@ -3,7 +3,7 @@
  *
  * These validate the raw definition objects (after `$variants` expansion)
  * and produce the typed `Part` / `Surface` / `Setup` / `PackageDef` values.
- * See docs/bgm-format.md for the format's concrete behavior.
+ * See docs/bgm/format.md for the format's concrete behavior.
  */
 import { z } from 'zod';
 import type { PackageDef, Part, Setup, Surface } from './types.js';

packages/bgm/src/types.ts

@@ -5,7 +5,7 @@
  * discovered as JSON objects from yaml/json/toml files and from markdown
  * code blocks, then assembled into a `Package` (see `collect.ts` / `emit.ts`).
  *
- * The concrete behavior of the format is described in `docs/bgm-format.md`.
+ * The concrete behavior of the format is described in `docs/bgm/format.md`.
  */
 
 /** Part value types. */

packages/bgm/src/variants.ts

@@ -2,7 +2,7 @@
  * The `$variants` directive: parse a CSV into a typed object array and
  * extend the original object with each row.
  *
- * Per docs/bgm-format.md §1:
+ * Per docs/bgm/format.md §1:
  * - The CSV's first row is the header, the second row is the type declaration
  *   (`string`, `number`, `string[]`, `[number;number;number;number]`, ...),
  *   the remaining rows are data.