@open-agent-toolkit/cli 0.3.28 → 0.3.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/README.md +2 -0
  2. package/assets/bundle-metadata.json +1 -1
  3. package/assets/docs/docs-tooling/add-docs-to-a-repo.md +2 -0
  4. package/assets/docs/docs-tooling/commands.md +47 -2
  5. package/assets/public-package-versions.json +4 -4
  6. package/assets/skills/authoring-docs/SKILL.md +2 -2
  7. package/assets/skills/authoring-docs/references/information-architecture.md +5 -2
  8. package/assets/skills/authoring-docs/references/page-templates/alert-runbook.md +63 -0
  9. package/assets/skills/authoring-docs/references/page-templates/command-reference.md +55 -0
  10. package/assets/skills/authoring-docs/references/page-templates/decisions-pointer.md +44 -0
  11. package/assets/skills/authoring-docs/references/page-templates/engineering-feature.md +53 -0
  12. package/assets/skills/authoring-docs/references/page-templates/per-area-agents.md +42 -0
  13. package/assets/skills/authoring-docs/references/page-templates/product-feature.md +49 -0
  14. package/assets/skills/authoring-docs/references/page-templates/qa-validation.md +59 -0
  15. package/assets/skills/authoring-docs/references/page-templates/screen-spec.md +51 -0
  16. package/assets/skills/authoring-docs/references/page-templates/skill-command-guide.md +44 -0
  17. package/assets/skills/authoring-docs/references/page-templates/solution-record.md +43 -0
  18. package/assets/skills/authoring-docs/references/templates.md +22 -2
  19. package/assets/skills/oat-docs-bootstrap/SKILL.md +11 -5
  20. package/dist/commands/docs/init/content.d.ts +23 -0
  21. package/dist/commands/docs/init/content.d.ts.map +1 -0
  22. package/dist/commands/docs/init/content.js +361 -0
  23. package/dist/commands/docs/init/index.d.ts.map +1 -1
  24. package/dist/commands/docs/init/index.js +32 -1
  25. package/dist/commands/docs/init/markdown.d.ts.map +1 -1
  26. package/dist/commands/docs/init/markdown.js +21 -2
  27. package/dist/commands/docs/init/resolve-options.d.ts +4 -1
  28. package/dist/commands/docs/init/resolve-options.d.ts.map +1 -1
  29. package/dist/commands/docs/init/resolve-options.js +4 -0
  30. package/dist/commands/docs/init/scaffold.d.ts.map +1 -1
  31. package/dist/commands/docs/init/scaffold.js +20 -1
  32. package/dist/release/public-package-contract.d.ts.map +1 -1
  33. package/dist/release/public-package-contract.js +10 -0
  34. package/package.json +3 -3
@@ -551,8 +551,8 @@ docs/
551
551
  ## IA Proposal
552
552
 
553
553
  Use for bootstrap or an existing-tree `--ia` analysis. This proposes structure;
554
- it neither persists an IA decision nor materializes a preset. Feature and QA
555
- validation page templates are not included; use the page-type guidance to
554
+ it neither persists an IA decision nor materializes a preset. Use the copyable
555
+ page assets below and the page-type guidance to
556
556
  plan their content.
557
557
 
558
558
  ````markdown
@@ -601,3 +601,23 @@ questions. Record an explicit choice before replacement or a second app.
601
601
  Existing docs default to analyze → apply of approved recommendations.
602
602
  No private exemplar text, copied external contents or unapproved moves.}
603
603
  ````
604
+
605
+ ## Copyable page assets
606
+
607
+ These Markdown bodies are the canonical source for approved preset scaffolds under
608
+ `contributing/templates/`. They are drafts, excluded from reader navigation and
609
+ manifest inventories through `documentation.nonReaderPaths`. Prefer local templates
610
+ when present; remove prompts and unneeded sections before publishing a reader page.
611
+ A Solution record captures an incident diagnosis, unlike the solution page type; a
612
+ Decisions pointer routes to records and never substitutes for an ADR.
613
+
614
+ - [Product feature](page-templates/product-feature.md) - Intended behavior and reader-visible boundaries for one feature or journey.
615
+ - [Engineering feature](page-templates/engineering-feature.md) - Implementation contracts and testing seams for one feature.
616
+ - [QA validation](page-templates/qa-validation.md) - Reproducible behavioral validation for one feature or journey.
617
+ - [Screen spec](page-templates/screen-spec.md) - Shared visible-state contract only for screens serving several journeys.
618
+ - [Alert runbook](page-templates/alert-runbook.md) - Triage, recovery and verification for a specific operational alert.
619
+ - [Solution record](page-templates/solution-record.md) - An incident diagnosis and fix, distinct from a capability solution guide.
620
+ - [Command reference](page-templates/command-reference.md) - Verified command inputs, outputs and mutation boundaries.
621
+ - [Skill or command guide](page-templates/skill-command-guide.md) - A reader task guide for invoking one skill or command.
622
+ - [Decisions pointer](page-templates/decisions-pointer.md) - A curated guide to consequential decisions, not a ledger or an ADR.
623
+ - [Per-area AGENTS](page-templates/per-area-agents.md) - Local authoring instructions excluded from reader navigation.
@@ -6,7 +6,7 @@ disable-model-invocation: true
6
6
  user-invocable: true
7
7
  allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
8
8
  metadata:
9
- version: '1.4.4'
9
+ version: '1.4.5'
10
10
  ---
11
11
 
12
12
  # Docs Bootstrap
@@ -120,8 +120,8 @@ The detailed framework procedures below apply to Fumadocs/MkDocs. When the selec
120
120
  2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
121
121
  Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
122
122
 
123
- 3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
124
- 4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
123
+ 3. **Invoke CLI:** For fresh setup, pass the explicitly approved nearest preset and anticipated reader-page count together as `--ia-preset <preset> --planned-pages <count>` only when both are advertised. Adoption never receives these flags. Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
124
+ 4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Without preset inputs, fresh setup creates only authored `index.md` and `contributing.md` in the target. For approved preset runs, compare the actual reader tree with the accepted selection: selected track directories at 15 or more anticipated reader pages, grouped root Contents and flat reader pages below 15, and flat structure for `flat-small` at any count. Inspect purpose, entry principle, useful section guidance and Contents links to actual pages. Verify the applicable `contributing/templates/` subset (all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets), retained when flat; `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay outside reader Contents and any separately configured manifest. Check the track table and accepted-selection guidance in `contributing.md`, separate from later IA persistence. In every Markdown run, verify no docs-root AGENTS, app package, framework config, dependencies, sidebar, site build, default manifest, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
125
125
  5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
126
126
  6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
127
127
  7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
@@ -392,7 +392,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
392
392
  `ask_user` with local/external source citations. Non-repo guidance stays read-only
393
393
  and private exemplars are never copied. Cite ordered sources in the proposal
394
394
  and final summary, including the built-in path when it wins.
395
- 6. Obtain explicit approval of the selected IA before persistence. After setup,
395
+ 6. Include the anticipated total reader-page count in the proposal (exclude contributor, template and toolchain pages). Obtain explicit approval of the selected IA and count before fresh preset materialization or persistence. For a fresh empty target, transport the approved nearest preset and count using the capability-gated flags below. Existing surfaces and explicit adoption retain their preserve-and-analyze flow without preset flags. After setup,
396
396
  use apply's `record-ia` procedure: target-repo `oat pjm doctor --json` and
397
397
  adoption check before `oat decision new`, an Information architecture section
398
398
  in the framework docs-app AGENTS.md or Markdown contributing page, and shared
@@ -401,7 +401,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
401
401
  it unrecorded. Do not silently initialize PJM. For an existing surface, hand
402
402
  off an analysis artifact plus approved recommendation IDs to apply, with
403
403
  individual approval for explicit record/restructure/tooling items.
404
- This IA selection stage does not materialize preset trees or change ownership for an existing app.
404
+ Preset materialization is CLI-owned and only for fresh empty targets; it does not record an IA decision or change ownership for an existing app.
405
405
  Sidebar ownership is separately chosen for existing framework apps; absent
406
406
  remains undeclared, Markdown ignores it, and no automatic nav generation is
407
407
  authorized by IA approval alone.
@@ -436,6 +436,7 @@ Base flags (always passed):
436
436
 
437
437
  Capability-gated flags (added only when the Capability Probe reports support):
438
438
 
439
+ - `--ia-preset {preset}` and `--planned-pages {count}` — pass together only for an explicitly approved fresh empty target, after both capabilities are advertised. IDs: `product-engineering-qa`, `consumer-maintainer`, `domain-engineering`, `task-type`, `toolkit-cli`, `flat-small`. Count is an integer of at least 1, with no implicit preset/default or interactive CLI choice. If either capability is absent, stop this handoff and recommend a CLI update. Do not substitute a file-write plan, copy templates manually, or use preset init to replace an existing surface.
439
440
  - `--site-name {siteName}` — only if `capabilities.siteNameFlag === true`. If absent, stop before scaffolding and recommend updating the CLI; do not rewrite the older template output.
440
441
  - `--no-root-patch` — only if `capabilities.noRootPatchFlag === true` and the Preflight / Conflict Resolution result says root package mutation should be skipped. This is recommended for no-root-package repositories or when the user explicitly chose no root mutation; current CLI builds also auto-skip when no root `package.json` exists, so the flag is optional documentation of intent, not a recovery mechanism.
441
442
 
@@ -445,12 +446,17 @@ Do not pass flags the CLI doesn't advertise. Never assume a flag exists because
445
446
 
446
447
  Before CLI invocation, run `$CLI_CMD docs init --help` once. Record:
447
448
 
449
+ - `iaPresetFlag` and `plannedPagesFlag`: whether `--ia-preset` and `--planned-pages` are both advertised. Require both for the approved fresh selection, including the Markdown path.
448
450
  - `siteNameFlag`: whether `--site-name` is advertised.
449
451
  - `agentsMdScaffold`: whether the installed framework template file list confirms native app-root `AGENTS.md` scaffolding; if unavailable, record unknown and verify actual output after invocation. Do not infer a CLI flag from this capability.
450
452
  - `noRootPatchFlag`: whether `--no-root-patch` is advertised.
451
453
 
452
454
  If the probe fails or returns no help, stop with the verbatim error and recommend updating or repairing the CLI. Never guess capabilities.
453
455
 
456
+ After preset init, inspect actual files and config before claiming success. At 15 or more anticipated reader pages, verify the selected track directories: triad `product/`, `engineering/`, `qa/`; consumer/maintainer `consumer/`, `maintainer/`; domain `engineering/`; task type `tutorials/`, `how-to/`, `reference/`, `explanation/`; toolkit `tools/`, `workflows/`. Below 15, or for `flat-small` at any count, verify grouped root Contents and flat reader pages instead. The exact CLI cutoff implements the approximate authoring heuristic, without selecting a different reader model. Track indexes own purpose, entry principle and useful section headings; they do not manufacture every section directory.
457
+
458
+ Verify the track table/accepted-selection guidance in framework app-root AGENTS, or Markdown `contributing.md`. Engineering stays hybrid (domain/implementation contracts alongside paired features); Product/QA enter by feature or journey. Check the applicable `contributing/templates/` subset: all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets. Size collapse retains the subset. Screen specs and per-area AGENTS are copyable only, never automatically instantiated. Verify `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay out of Contents, sidebar and manifest. `excludes` remains manifest-only; pinned MkDocs may still render non-reader routes and retains `use_directory_urls: false`. Run the real checker and framework nav `--check`; repair failures without suppressing rules. Keep approved-selection evidence separate from the later `record-ia` persistence/adoption result.
459
+
454
460
  After scaffolding, inspect `<appRoot>/AGENTS.md`: absence is a missing-capability finding with analyze/manual upgrade advice; any existing file is preserved. No missing-file bridge is permitted. Check template output against the current scaffold contract. Older output with missing metadata, unresolved Node-version advice, missing generated-files guidance, extension-less Contents links, duplicated agent instructions, or a Fumadocs wrapper that loses static export settings becomes a finding under `oat-docs-analyze`'s legacy scaffold checks (load that skill from installed scope and resolve `references/legacy-scaffold-checks.md` from its own directory). Record the observed path and evidence, then offer analyze; do not reinstate template patches. Ambiguous or user-authored shapes are reported for review, never overwritten.
455
461
 
456
462
  **3c. Invoke the CLI.**
@@ -0,0 +1,23 @@
1
+ export declare const IA_PRESETS: readonly ['product-engineering-qa', 'consumer-maintainer', 'domain-engineering', 'task-type', 'toolkit-cli', 'flat-small'];
2
+ export type IaPreset = (typeof IA_PRESETS)[number];
3
+ export interface PresetSelection {
4
+ iaPreset?: IaPreset;
5
+ plannedPages?: number;
6
+ }
7
+ /** Validate the opt-in pair before planning or writing any scaffold files. */
8
+ export declare function resolvePresetSelection(preset?: string, count?: string | number): PresetSelection;
9
+ export declare function mergeTemplateExclusion(paths?: string[]): string[];
10
+ /** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
11
+ export declare function planPresetContent(options: PresetSelection & {
12
+ assetsRoot: string;
13
+ siteName: string;
14
+ siteDescription?: string;
15
+ markdown: boolean;
16
+ }): Promise<{
17
+ files: {
18
+ name: string;
19
+ content: string;
20
+ }[];
21
+ guidance: string;
22
+ } | null>;
23
+ //# sourceMappingURL=content.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/content.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,YACrB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,CACJ,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GACtB,eAAe,CAiBjB;AAmSD,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAErE;AAQD,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC;IACT,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,CAwFR"}
@@ -0,0 +1,361 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ export const IA_PRESETS = [
4
+ 'product-engineering-qa',
5
+ 'consumer-maintainer',
6
+ 'domain-engineering',
7
+ 'task-type',
8
+ 'toolkit-cli',
9
+ 'flat-small',
10
+ ];
11
+ /** Validate the opt-in pair before planning or writing any scaffold files. */
12
+ export function resolvePresetSelection(preset, count) {
13
+ if (preset === undefined && count === undefined)
14
+ return {};
15
+ if (preset === undefined || count === undefined)
16
+ throw new Error('--ia-preset and --planned-pages are required together.');
17
+ if (!IA_PRESETS.includes(preset))
18
+ throw new Error(`Unknown IA preset "${preset}". Choose: ${IA_PRESETS.join(', ')}.`);
19
+ if (!/^\d+$/.test(String(count)) ||
20
+ !Number.isSafeInteger(Number(count)) ||
21
+ Number(count) < 1)
22
+ throw new Error('--planned-pages must be an integer of at least 1 (anticipated reader pages only).');
23
+ return { iaPreset: preset, plannedPages: Number(count) };
24
+ }
25
+ const engineering = {
26
+ path: 'engineering',
27
+ title: 'Engineering',
28
+ principle: 'Domain and implementation contracts alongside paired feature pages',
29
+ purpose: 'Engineering is hybrid: enter by domain or implementation contract when changing shared behavior, and by feature when following its paired Product and QA pages.',
30
+ sections: [
31
+ [
32
+ 'Domain contracts',
33
+ 'Place shared domain rules, interface boundaries and invariants here; link the features that depend on them.',
34
+ ],
35
+ [
36
+ 'Feature implementation',
37
+ 'Link implementation details for each feature to its Product intent, shared domain contracts and QA validation.',
38
+ ],
39
+ [
40
+ 'Operations and failure modes',
41
+ 'Place diagnosis, recovery and operational limits here; link runbooks and incident solution records.',
42
+ ],
43
+ ],
44
+ };
45
+ const TRACKS = {
46
+ 'product-engineering-qa': [
47
+ {
48
+ path: 'product',
49
+ title: 'Product',
50
+ principle: 'Feature or journey',
51
+ purpose: 'Product readers enter by feature or journey to understand availability, intended behavior and user-visible boundaries.',
52
+ sections: [
53
+ [
54
+ 'Availability',
55
+ 'Describe who can use each feature, supported environments and known availability limits; link its feature page.',
56
+ ],
57
+ [
58
+ 'Journeys and behavior',
59
+ 'Place feature goals and ordered user journeys here, with their expected user-visible outcomes.',
60
+ ],
61
+ [
62
+ 'States and boundaries',
63
+ 'Document visible states, transitions, empty and error behavior, and what each feature excludes.',
64
+ ],
65
+ ],
66
+ },
67
+ engineering,
68
+ {
69
+ path: 'qa',
70
+ title: 'QA',
71
+ principle: 'Feature or journey with reproducible verification',
72
+ purpose: 'QA readers enter by feature or journey to reproduce behavior with named seeds, ready signals, exact expectations and cleanup.',
73
+ sections: [
74
+ [
75
+ 'Seeds and configuration',
76
+ 'Place reproducible test data, configuration and ready signals here; identify safe setup and cleanup.',
77
+ ],
78
+ [
79
+ 'Scenarios',
80
+ 'Organize validation by feature or journey, with actions, exact expectations and links to the supported contract.',
81
+ ],
82
+ [
83
+ 'Execution evidence',
84
+ 'Keep dated runs, observed results and discrepancies here, separate from planned automation and implemented assertions.',
85
+ ],
86
+ ],
87
+ },
88
+ ],
89
+ 'consumer-maintainer': [
90
+ {
91
+ path: 'consumer',
92
+ title: 'Consumer',
93
+ principle: 'Reader task and supported contract',
94
+ purpose: 'Consumers enter by the task they need to complete and the supported contract they can rely on.',
95
+ sections: [
96
+ [
97
+ 'Start here',
98
+ 'Link the shortest supported first task, including prerequisites and a result the reader can verify.',
99
+ ],
100
+ [
101
+ 'Tasks',
102
+ 'Place bounded procedures for consumer goals here; link required inputs and verification steps.',
103
+ ],
104
+ [
105
+ 'Supported reference',
106
+ 'Collect supported interfaces, inputs, outputs and compatibility limits for consumer lookup.',
107
+ ],
108
+ ],
109
+ },
110
+ {
111
+ path: 'maintainer',
112
+ title: 'Maintainer',
113
+ principle: 'Change, operation and maintenance responsibility',
114
+ purpose: 'Maintainers enter by the responsibility they own: implementation, delivery, operations or support of the shared contract.',
115
+ sections: [
116
+ [
117
+ 'Implementation contracts',
118
+ 'Place internal interfaces, invariants and ownership boundaries here for maintainers changing behavior.',
119
+ ],
120
+ [
121
+ 'Delivery',
122
+ 'Document release preparation, compatibility checks, rollout and rollback responsibilities here.',
123
+ ],
124
+ [
125
+ 'Operations',
126
+ 'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
127
+ ],
128
+ ],
129
+ },
130
+ ],
131
+ 'domain-engineering': [engineering],
132
+ 'task-type': [
133
+ {
134
+ path: 'tutorials',
135
+ title: 'Tutorials',
136
+ principle: 'Learning by a complete safe exercise',
137
+ purpose: 'Learners enter through a guided exercise with a clear starting state and an independently verifiable result.',
138
+ sections: [
139
+ [
140
+ 'Prerequisites',
141
+ 'State the required knowledge, access, environment and safe starting data before the reader begins.',
142
+ ],
143
+ [
144
+ 'Guided exercise',
145
+ 'Walk through one complete learning exercise in order, explaining what each step demonstrates.',
146
+ ],
147
+ [
148
+ 'Expected result',
149
+ 'Show how to recognize a successful exercise and compare the observed result with the learning goal.',
150
+ ],
151
+ ],
152
+ },
153
+ {
154
+ path: 'how-to',
155
+ title: 'How-to',
156
+ principle: 'One concrete reader task',
157
+ purpose: 'Readers who know their goal enter by task, confirm prerequisites and follow a bounded procedure.',
158
+ sections: [
159
+ [
160
+ 'Prerequisites',
161
+ 'State the required knowledge, access, environment and safe starting data before the reader begins.',
162
+ ],
163
+ [
164
+ 'Procedure',
165
+ 'Give the ordered actions for one concrete task, including decision points and supported alternatives.',
166
+ ],
167
+ [
168
+ 'Verification and cleanup',
169
+ 'Explain how to check the task result, remove temporary resources and recover from an incomplete attempt.',
170
+ ],
171
+ ],
172
+ },
173
+ {
174
+ path: 'reference',
175
+ title: 'Reference',
176
+ principle: 'Lookup by supported interface or contract',
177
+ purpose: 'Readers enter by a named interface or contract to find exact inputs, outputs, defaults and supported limits.',
178
+ sections: [
179
+ [
180
+ 'Interfaces',
181
+ 'Describe supported commands, APIs or configuration fields with their accepted inputs and observable outputs.',
182
+ ],
183
+ [
184
+ 'Defaults and limits',
185
+ 'Record source-verified defaults, supported ranges and compatibility constraints for precise lookup.',
186
+ ],
187
+ [
188
+ 'Failure behavior',
189
+ 'Describe errors, partial outcomes and recovery expectations for each supported interface.',
190
+ ],
191
+ ],
192
+ },
193
+ {
194
+ path: 'explanation',
195
+ title: 'Explanation',
196
+ principle: 'Understanding concepts and tradeoffs',
197
+ purpose: 'Readers enter by a concept or design question to understand relationships, constraints and tradeoffs.',
198
+ sections: [
199
+ [
200
+ 'Concepts',
201
+ 'Explain the vocabulary and mental models readers need before following task or reference pages.',
202
+ ],
203
+ [
204
+ 'Relationships',
205
+ 'Show how the concepts and components depend on one another, linking their canonical contracts.',
206
+ ],
207
+ [
208
+ 'Tradeoffs',
209
+ 'Explain design choices, alternatives and constraints, linking the decisions that establish them.',
210
+ ],
211
+ ],
212
+ },
213
+ ],
214
+ 'toolkit-cli': [
215
+ {
216
+ path: 'tools',
217
+ title: 'Tools',
218
+ principle: 'Tool, skill or command invocation',
219
+ purpose: 'Tool users enter by command or skill, confirm prerequisites and mutation scope, then inspect the expected output.',
220
+ sections: [
221
+ [
222
+ 'Invocation',
223
+ 'Document how to invoke each command or skill, including prerequisites and supported examples.',
224
+ ],
225
+ [
226
+ 'Inputs and side effects',
227
+ 'Describe accepted arguments and configuration, mutation scope, required approval and external effects.',
228
+ ],
229
+ [
230
+ 'Outputs',
231
+ 'Document result fields, generated artifacts, exit behavior and the next action each outcome supports.',
232
+ ],
233
+ ],
234
+ },
235
+ {
236
+ path: 'workflows',
237
+ title: 'Workflows',
238
+ principle: 'Reader goal across a sequence of tools',
239
+ purpose: 'Workflow users enter by their goal and follow an ordered sequence of tools with explicit authority and handoffs.',
240
+ sections: [
241
+ [
242
+ 'Starting state',
243
+ 'State the reader goal, required inputs, authority and ready signals before a workflow begins.',
244
+ ],
245
+ [
246
+ 'Sequence and handoffs',
247
+ 'Order the tools and decisions, naming what each step passes to the next responsible actor.',
248
+ ],
249
+ [
250
+ 'Completion evidence',
251
+ 'Define the observable result that closes the workflow and where to retain its execution evidence.',
252
+ ],
253
+ ],
254
+ },
255
+ ],
256
+ 'flat-small': [
257
+ {
258
+ path: 'start-here',
259
+ title: 'Start here',
260
+ principle: 'Reader goal in a flat grouped index',
261
+ purpose: 'Readers enter by their immediate goal, using one grouped index instead of navigating a hierarchy before choosing a task.',
262
+ sections: [
263
+ [
264
+ 'Reader tasks',
265
+ 'Group links by the immediate goals readers need to accomplish, keeping each procedure focused.',
266
+ ],
267
+ [
268
+ 'Reference',
269
+ 'Link canonical interface and configuration facts for lookup without repeating them in task pages.',
270
+ ],
271
+ [
272
+ 'Operations',
273
+ 'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
274
+ ],
275
+ ],
276
+ },
277
+ ],
278
+ };
279
+ const SUPPORT_TEMPLATES = [
280
+ 'alert-runbook',
281
+ 'solution-record',
282
+ 'command-reference',
283
+ 'skill-command-guide',
284
+ 'decisions-pointer',
285
+ 'per-area-agents',
286
+ ];
287
+ const TRIAD_TEMPLATES = [
288
+ 'product-feature',
289
+ 'engineering-feature',
290
+ 'qa-validation',
291
+ 'screen-spec',
292
+ ...SUPPORT_TEMPLATES,
293
+ ];
294
+ export function mergeTemplateExclusion(paths = []) {
295
+ return [...new Set([...paths, 'contributing/templates/**'])];
296
+ }
297
+ function page(title, description, body) {
298
+ return `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---\n\n# ${title}\n\n${body}\n`;
299
+ }
300
+ function link(title, path, description) {
301
+ return `- [${title}](${path}) - ${description}`;
302
+ }
303
+ /** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
304
+ export async function planPresetContent(options) {
305
+ const selection = resolvePresetSelection(options.iaPreset, options.plannedPages);
306
+ if (!selection.iaPreset)
307
+ return null;
308
+ const preset = selection.iaPreset;
309
+ const tracks = TRACKS[preset];
310
+ const flat = selection.plannedPages < 15 || preset === 'flat-small';
311
+ const files = [];
312
+ const rootLinks = [];
313
+ for (const track of tracks) {
314
+ const guideName = flat ? `${track.path}.md` : `${track.path}/start-here.md`;
315
+ const indexName = `${track.path}/index.md`;
316
+ const guideTitle = `${track.title}: choose a safe first task`;
317
+ const guide = `${track.purpose}\n\n## Choose the right contract\n\nIdentify your goal and supported environment before acting. Check availability, permissions and prerequisites in the repository's current source and reviewed guidance. A missing fact is a review gap, not permission to guess.\n\n## Establish a safe starting state\n\nPrefer an isolated example or read-only inspection. Record relevant configuration and inputs, avoid real personal data, and identify the owner of any external dependency. For changes, confirm approval and a cleanup or rollback route before proceeding.\n\n## Verify the result\n\nCompare the observable result with the supported contract. Keep concepts in prose; use backticks only for literals verified in source. Separate proposed automation, implemented test assertions and dated execution evidence. Escalate a discrepancy with the input, expected result and observed evidence.\n\n## Continue\n\nReturn to the [${flat ? 'documentation map' : `${track.title} map`}](index.md) to choose the next reader goal.\n`;
318
+ files.push({
319
+ name: guideName,
320
+ content: page(guideTitle, `Select prerequisites, boundaries and a verifiable first result for ${track.title.toLowerCase()} work.`, guide),
321
+ });
322
+ if (flat) {
323
+ rootLinks.push(`### ${track.title}\n\n${track.purpose}\n\n${link(guideTitle, guideName, 'Choose a safe starting state and verify the result.')}\n`);
324
+ }
325
+ else {
326
+ const sections = track.sections
327
+ .map(([title, guidance]) => `## ${title}\n\n${guidance}`)
328
+ .join('\n\n');
329
+ files.push({
330
+ name: indexName,
331
+ content: page(track.title, track.purpose, `${track.purpose}\n\nEntry principle: ${track.principle}. This track owns its canonical facts; route to shared contracts and paired pages rather than copying their claims.\n\n## Contents\n\n${link(guideTitle, 'start-here.md', 'Choose a safe starting state and verify the result.')}\n\n${sections}`),
332
+ });
333
+ rootLinks.push(link(track.title, indexName, track.purpose));
334
+ }
335
+ }
336
+ const contributor = options.markdown
337
+ ? 'contributing.md'
338
+ : 'contributing/index.md';
339
+ rootLinks.push(`${flat ? '### Contributing\n\n' : ''}${link('Contributing', contributor, 'Authoring conventions and template selection.')}\n`);
340
+ files.unshift({
341
+ name: 'index.md',
342
+ content: page(options.siteName, options.siteDescription?.trim() ||
343
+ `Reader entry points for the ${preset} model.`, `Choose the entry matching your work context. This documentation uses the ${preset} reader model; its entry principles guide placement, while page count controls materialized depth. Confirm repository-specific behavior against source before acting.\n\n## Contents\n\n${rootLinks.join('\n')}`),
344
+ });
345
+ const templates = preset === 'product-engineering-qa'
346
+ ? TRIAD_TEMPLATES
347
+ : preset === 'domain-engineering'
348
+ ? ['engineering-feature', ...SUPPORT_TEMPLATES]
349
+ : SUPPORT_TEMPLATES;
350
+ for (const name of templates) {
351
+ files.push({
352
+ name: `contributing/templates/${name}.md`,
353
+ content: await readFile(join(options.assetsRoot, 'skills', 'authoring-docs', 'references', 'page-templates', `${name}.md`), 'utf8'),
354
+ });
355
+ }
356
+ const table = tracks
357
+ .map((track) => `| ${flat ? `index.md (group: ${track.title})` : `${track.path}/`} | ${track.title} | ${track.principle} |`)
358
+ .join('\n');
359
+ const guidance = `## Preset selection\n\nAccepted selection supplied to init: ${preset}; anticipated reader pages: ${selection.plannedPages}. ${flat ? 'Reader structure is collapsed into grouped root headings.' : 'Reader directories are materialized at 15 or more anticipated pages.'} Contributor, template and toolchain pages are outside this reader-page estimate.\n\n| Location | Reader track | Entry principle |\n| --- | --- | --- |\n${table}\n\n${tracks.map((t) => t.purpose).join('\n\n')}\n\nUse contributing/templates/ as non-reader drafting assets. Screen specs are conditional on several journeys sharing a screen; no screen page or per-track AGENTS file is created automatically. Preserve canonical facts and paired links. This selection is not a persisted IA decision: complete the existing explicit approval/adoption and record-ia flow before claiming an authored IA record or config mirror. It does not initialize project management. Existing surfaces route to analyze and individually approved apply; init never restructures them.\n`;
360
+ return { files, guidance };
361
+ }
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"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"}
@@ -9,6 +9,7 @@ import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
9
9
  import { resolveAssetsRoot } from '../../../fs/assets.js';
10
10
  import { atomicWriteJson, fileExists } from '../../../fs/io.js';
11
11
  import { Command, Option } from 'commander';
12
+ import { mergeTemplateExclusion } from './content.js';
12
13
  import { buildDocsCommands } from './docs-commands.js';
13
14
  import { applyMarkdownDocsPlan, MarkdownDocsWriteError, planMarkdownDocs, validateMarkdownConfig, validateMarkdownTarget, } from './markdown.js';
14
15
  import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
@@ -107,8 +108,27 @@ const DEFAULT_DEPENDENCIES = {
107
108
  root: plan.targetDir,
108
109
  tooling: 'markdown',
109
110
  index: `${plan.targetDir}/index.md`,
111
+ ...(options.iaPreset
112
+ ? {
113
+ nonReaderPaths: mergeTemplateExclusion(latest.documentation?.nonReaderPaths),
114
+ }
115
+ : {}),
110
116
  };
111
- await writeOatConfig(context.cwd, latest);
117
+ if (options.iaPreset) {
118
+ const configPath = join(context.cwd, '.oat/config.json');
119
+ const raw = (await fileExists(configPath))
120
+ ? JSON.parse(await readFile(configPath, 'utf8'))
121
+ : latest;
122
+ await atomicWriteJson(configPath, {
123
+ ...raw,
124
+ documentation: {
125
+ ...raw.documentation,
126
+ ...latest.documentation,
127
+ },
128
+ });
129
+ }
130
+ else
131
+ await writeOatConfig(context.cwd, latest);
112
132
  report.configStatus = 'updated';
113
133
  }
114
134
  catch (error) {
@@ -145,6 +165,8 @@ const DEFAULT_DEPENDENCIES = {
145
165
  enabled: options.rootPatch,
146
166
  });
147
167
  const config = await readOatConfig(context.cwd);
168
+ if (options.iaPreset)
169
+ result.documentationConfig.nonReaderPaths = mergeTemplateExclusion(config.documentation?.nonReaderPaths);
148
170
  config.documentation = {
149
171
  ...config.documentation,
150
172
  ...result.documentationConfig,
@@ -250,6 +272,8 @@ async function runDocsInitCommand(context, options, dependencies) {
250
272
  interactive: context.interactive,
251
273
  acceptDefaults: options.yes ?? false,
252
274
  providedFramework: options.framework,
275
+ providedIaPreset: options.iaPreset,
276
+ providedPlannedPages: options.plannedPages,
253
277
  providedAdopt: options.adopt,
254
278
  providedAppName: options.appName,
255
279
  providedSiteName: options.siteName,
@@ -276,6 +300,11 @@ async function runDocsInitCommand(context, options, dependencies) {
276
300
  }
277
301
  const inapplicableOptions = [];
278
302
  const existingConfig = await dependencies.readOatConfig(context.cwd);
303
+ if (resolved.iaPreset &&
304
+ (existingConfig.documentation?.root ||
305
+ existingConfig.documentation?.ia ||
306
+ existingConfig.documentation?.navOwner))
307
+ throw new Error('Preset init cannot replace an existing docs surface or navigation ownership. Use oat-docs-analyze and individually approved oat-docs-apply.');
279
308
  if (resolved.framework === 'markdown') {
280
309
  resolved.targetDir = await validateMarkdownTarget(context.cwd, resolved.targetDir);
281
310
  validateMarkdownConfig(context.cwd, resolved.targetDir, existingConfig.documentation);
@@ -464,6 +493,8 @@ export function createDocsInitCommand(overrides = {}) {
464
493
  .addOption(new Option('--app-name <name>', 'Docs app name (inapplicable to Markdown)'))
465
494
  .addOption(new Option('--site-name <name>', 'Site display title or Markdown documentation title'))
466
495
  .addOption(new Option('--target-dir <path>', 'Docs directory (Markdown defaults to docs; requires a dedicated directory)'))
496
+ .option('--ia-preset <preset>', 'Approved IA preset (requires --planned-pages; fresh empty target only)')
497
+ .option('--planned-pages <count>', 'Anticipated reader pages: integer >=1; collapse below 15 (requires --ia-preset)')
467
498
  .addOption(new Option('--description <text>', 'Documentation description'))
468
499
  .addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([
469
500
  'none',
@@ -1 +1 @@
1
- {"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA2E3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA8E7B"}
1
+ {"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAuG3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA+E7B"}