@libar-dev/architect 1.0.0-pre.3 → 1.0.0-pre.4

package/docs-live/product-areas/CONFIGURATION.md

@@ -284,6 +284,16 @@ interface ArchitectProjectConfig {
   /** Path to custom workflow config JSON (relative to config file) */
   readonly workflowPath?: string;
 
+  // --- Project Identity ---
+
+  /** Project metadata for customizing generated docs (package name, purpose, license) */
+  readonly project?: ProjectMetadata;
+
+  /** Override format type examples in TaxonomyCodec output */
+  readonly tagExampleOverrides?: Partial<
+    Record<FormatType, { description?: string; example?: string }>
+  >;
+
   // --- Codec Options ---
 
   /**
@@ -320,6 +330,8 @@ interface ArchitectProjectConfig {
 | generatorOverrides    | Per-generator source and output overrides                                                                                                                                                                                                                                                                                                                               |
 | contextInferenceRules | Rules for auto-inferring bounded context from file paths                                                                                                                                                                                                                                                                                                                |
 | workflowPath          | Path to custom workflow config JSON (relative to config file)                                                                                                                                                                                                                                                                                                           |
+| project               | Project metadata for customizing generated docs (package name, purpose, license)                                                                                                                                                                                                                                                                                        |
+| tagExampleOverrides   | Override format type examples in TaxonomyCodec output                                                                                                                                                                                                                                                                                                                   |
 | codecOptions          | Per-codec options for fine-tuning document generation. Keys match codec names (e.g., 'business-rules', 'patterns'). Passed through to codec factories at generation time.                                                                                                                                                                                               |
 | referenceDocConfigs   | Reference document configurations for convention-based doc generation. Each config defines one reference document's content composition via convention tags, shape selectors, behavior categories, and diagram scopes. When not specified, no reference generators are registered. Import `LIBAR_REFERENCE_CONFIGS` from the generators module to use the built-in set. |
 
@@ -372,17 +384,17 @@ interface SourcesConfig {
 
 ```typescript
 interface OutputConfig {
-  /** Output directory for generated docs (default: 'docs/architecture') */
+  /** Output directory for generated docs (default: 'docs-live') */
   readonly directory?: string;
   /** Overwrite existing files (default: false) */
   readonly overwrite?: boolean;
 }
 ```
 
-| Property  | Description                                                        |
-| --------- | ------------------------------------------------------------------ |
-| directory | Output directory for generated docs (default: 'docs/architecture') |
-| overwrite | Overwrite existing files (default: false)                          |
+| Property  | Description                                                |
+| --------- | ---------------------------------------------------------- |
+| directory | Output directory for generated docs (default: 'docs-live') |
+| overwrite | Overwrite existing files (default: false)                  |
 
 ### GeneratorSourceOverride (interface)
 
@@ -463,19 +475,27 @@ interface ResolvedProjectConfig {
   readonly codecOptions?: CodecOptions;
   /** Reference document configurations (empty array if none) */
   readonly referenceDocConfigs: readonly ReferenceDocConfig[];
+  /** Project metadata (auto-read from package.json if not provided) */
+  readonly project?: ProjectMetadata;
+  /** Format type example overrides */
+  readonly tagExampleOverrides?: Partial<
+    Record<FormatType, { description?: string; example?: string }>
+  >;
 }
 ```
 
-| Property              | Description                                                |
-| --------------------- | ---------------------------------------------------------- |
-| sources               | Resolved source globs (stubs merged, defaults applied)     |
-| output                | Resolved output config with all defaults                   |
-| generators            | Default generator names                                    |
-| generatorOverrides    | Per-generator source overrides                             |
-| contextInferenceRules | Context inference rules (user rules prepended to defaults) |
-| workflowPath          | Workflow config path (null if not specified)               |
-| codecOptions          | Per-codec options for document generation (empty if none)  |
-| referenceDocConfigs   | Reference document configurations (empty array if none)    |
+| Property              | Description                                                    |
+| --------------------- | -------------------------------------------------------------- |
+| sources               | Resolved source globs (stubs merged, defaults applied)         |
+| output                | Resolved output config with all defaults                       |
+| generators            | Default generator names                                        |
+| generatorOverrides    | Per-generator source overrides                                 |
+| contextInferenceRules | Context inference rules (user rules prepended to defaults)     |
+| workflowPath          | Workflow config path (null if not specified)                   |
+| codecOptions          | Per-codec options for document generation (empty if none)      |
+| referenceDocConfigs   | Reference document configurations (empty array if none)        |
+| project               | Project metadata (auto-read from package.json if not provided) |
+| tagExampleOverrides   | Format type example overrides                                  |
 
 ### ResolvedSourcesConfig (interface)
 
@@ -953,7 +973,7 @@ const PRESETS: Record<PresetName, ArchitectConfig>;
 
 | Rule                                                 | Invariant                                                                                                                                                                                            | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Default workflow is built from an inline constant    | `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. | The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, process-api) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise.                                                                                                                                                                                     |
+| Default workflow is built from an inline constant    | `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. | The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise.                                                                                                                                                                               |
 | Custom workflow files still work via --workflow flag | `loadWorkflowFromPath()` remains available for projects that need custom workflow definitions. The `--workflow <file>` CLI flag and `workflowPath` config field continue to work.                    | The inline default replaces file-based _default_ loading, not file-based _custom_ loading. Projects may define custom phases or additional statuses via JSON files.                                                                                                                                                                                                                                                                                                                                              |
 | FSM validation and Process Guard are not affected    | The FSM transition matrix, protection levels, and Process Guard rules remain hardcoded in `src/validation/fsm/` and `src/lint/process-guard/`. They do not read from `LoadedWorkflow`.               | FSM and workflow are separate concerns. FSM enforces status transitions (4-state model from PDR-005). Workflow defines phase structure (6-phase USDP). The workflow JSON declared `transitionsTo` on its statuses, but no code ever read those values — the FSM uses its own `VALID_TRANSITIONS` constant. This separation is correct and intentional. Blast radius analysis confirmed zero workflow imports in: - src/validation/fsm/ (4 files) - src/lint/process-guard/ (5 files) - src/taxonomy/ (all files) |
 | Workflow as a configurable preset field is deferred  | The inline default workflow constant is the only workflow source until preset integration is implemented. No preset or project config field exposes workflow customization.                          | Coupling workflow into the preset/config system before the inline fix ships would widen the blast radius and risk type regressions across all config consumers.                                                                                                                                                                                                                                                                                                                                                  |
@@ -974,7 +994,7 @@ const PRESETS: Record<PresetName, ArchitectConfig>;
 | Default config provides sensible fallbacks | A config created without user input must have isDefault=true and empty source collections. | Downstream consumers need a safe starting point when no config file exists.                               |
 | Preset creates correct taxonomy instance   | Each preset must produce a taxonomy with the correct number of categories and tag prefix.  | Presets are the primary user-facing configuration — wrong category counts break downstream scanning.      |
 | Stubs are merged into typescript sources   | Stub glob patterns must appear in resolved typescript sources alongside original globs.    | Stubs extend the scanner's source set without requiring users to manually list them.                      |
-| Output defaults are applied                | Missing output configuration must resolve to "docs/architecture" with overwrite=false.     | Consistent defaults prevent accidental overwrites and establish a predictable output location.            |
+| Output defaults are applied                | Missing output configuration must resolve to "docs-live" with overwrite=false.             | Consistent defaults prevent accidental overwrites and establish a predictable output location.            |
 | Generator defaults are applied             | A config with no generators specified must default to the "patterns" generator.            | Patterns is the most commonly needed output — defaulting to it reduces boilerplate.                       |
 | Context inference rules are prepended      | User-defined inference rules must appear before built-in defaults in the resolved array.   | Prepending gives user rules priority during context matching without losing defaults.                     |
 | Config path is carried from options        | The configPath from resolution options must be preserved unchanged in resolved config.     | Downstream tools need the original config file location for error reporting and relative path resolution. |
@@ -1031,9 +1051,9 @@ const PRESETS: Record<PresetName, ArchitectConfig>;
 | Init detects existing project context before making changes               | The init command reads the target directory for package.json, tsconfig.json, architect.config.ts (or .js), and monorepo markers before prompting or generating any files. Detection results determine which steps are skipped.                                                                                                                                                                  | Blindly generating files overwrites user configuration and breaks working setups. Context detection enables safe adoption into existing projects by skipping steps that are already complete.     |
 | Interactive prompts configure preset and source paths with smart defaults | The init command prompts for preset selection from the two available presets (libar-generic, ddd-es-cqrs) with descriptions, and for source glob paths with defaults inferred from project structure. The --yes flag skips non-destructive selection prompts and uses defaults. Destructive overwrites require an explicit --force flag; otherwise init exits without modifying existing files. | New users do not know which preset to choose or what glob patterns to use. Smart defaults reduce decisions to confirmations. The --yes flag enables scripted adoption in CI.                      |
 | Generated config file uses defineConfig with correct imports              | The generated architect.config.ts (or .js) imports defineConfig from the correct path, uses the selected preset, and includes configured source globs. An existing config file is never overwritten without confirmation.                                                                                                                                                                       | The config file is the most important artifact. An incorrect import path or malformed glob causes every subsequent command to fail. The overwrite guard prevents destroying custom configuration. |
-| Npm scripts are injected using bin command names                          | Injected scripts reference bin names (process-api, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via --esm flag.                                                                                                                                               | The tutorial uses long fragile dist paths. Bin commands are the stable public API. Setting type:module ensures ESM imports work for the config.                                                   |
+| Npm scripts are injected using bin command names                          | Injected scripts reference bin names (pattern-graph-cli, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via --esm flag.                                                                                                                                         | The tutorial uses long fragile dist paths. Bin commands are the stable public API. Setting type:module ensures ESM imports work for the config.                                                   |
 | Directory structure and example annotation enable immediate first run     | The init command creates directories for configured source globs and generates one example annotated TypeScript file with the minimum annotation set (opt-in marker, pattern tag, status, category, description).                                                                                                                                                                               | Empty source globs produce a confusing "0 patterns" result. An example file proves the pipeline works and teaches annotation syntax by example.                                                   |
-| Init validates the complete setup by running the pipeline                 | After all files are generated, init runs process-api overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information.                                                                                                                                                                                    | Generating files without verification produces false confidence. Running the pipeline as the final step proves config, globs, directories, and the example annotation all work together.          |
+| Init validates the complete setup by running the pipeline                 | After all files are generated, init runs pattern-graph-cli overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information.                                                                                                                                                                              | Generating files without verification produces false confidence. Running the pipeline as the final step proves config, globs, directories, and the example annotation all work together.          |
 
 ### Source Merging