bc-atlas 0.14.0 → 0.16.0

package/.bca.example.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "./node_modules/bc-atlas/schemas/bca.schema.json",
   "view": "project",
   "projectRoot": ".",
   "direction": "right",
@@ -71,6 +72,16 @@
     "strictLayers": false,
     "maxObjects": 1500,
     "couplingWeights": { "reads": 2, "subscribes": 1 },
+    "proposal": {
+      "groupBy": "auto",
+      "startFrom": ["namespace", "folder"],
+      "ignore": ["permits", "includes"],
+      "granularity": 1,
+      "sharedCore": true,
+      "keep": [{ "name": "Core", "match": ["namespace:Contoso.Core"], "description": "Defined by the team" }],
+      "exclude": ["type:permissionset", "folder:test"],
+      "moves": { "minGain": 2, "limit": 50 }
+    },
     "severity": "error",
     "unassigned": "warning",
     "severities": {

package/CHANGELOG.md

@@ -4,6 +4,196 @@ All notable changes to BC Atlas will be documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 follows [Semantic Versioning](https://semver.org/).
 
+## 0.16.0 - 2026-11-06
+
+### Added
+
+- You decide what the architecture proposal takes into account and how it
+  builds components: `architecture.proposal` in `.bca.json` sets the grouping,
+  the structures it starts from (`startFrom`), relation kinds that never shape
+  components (`ignore`), how finely it splits (`granularity`,
+  `appGranularity`), whether a shared core forms (`sharedCore`), components
+  you define yourself (`keep`), objects that should not shape components
+  (`exclude`), and which moves it lists (`moves`). `bca architecture
+  --propose` has `--start-from`, `--ignore`, `--granularity`, and
+  `--shared-core`, and the MCP tool and the app take the same settings.
+- Every proposal says how it was made (`proposal.basis` in JSON, **How this
+  proposal was made** in the reports, **What was considered** in the app):
+  which objects and relation kinds shaped it, their weights, the settings, and
+  whether each value came from `.bca.json` or an option.
+- `schemas/bca.schema.json` describes `.bca.json`; the VS Code extension
+  applies it, so `.bca.json` gets completion and checks.
+- The system handbook (`bca export --view handbook`, the `handbook` task of
+  `bca run` and the GitHub Action) explains an app across all its objects, on
+  pages generated from the source:
+  - what it consists of: apps, components, object types, central objects
+  - its events, with publishers and subscribers
+  - its data: who inserts, modifies, deletes, and reads each table
+  - its permission sets, and the tables none of them covers
+  - its interfaces, with implementations and enum bindings
+  - what users can open, by usage category, and its APIs
+  - its code health: complexity, size, obsolete code, documentation coverage
+
+  See `docs/handbook.md` and `examples/handbook`.
+- The handbook links object names to their pages in the object catalog: use
+  `--catalog <folder>`, or `handbook.catalog` in `.bca.json`. `bca run` links
+  them on its own when the same run writes the catalog.
+- The app and the VS Code panel have a **Handbook** page. Object names there
+  open their object page.
+- Objects from symbol packages (`.app`) carry metadata too: caption, access,
+  obsolete state, data classification, kind, and size, read from
+  `SymbolReference.json`. Objects that newer symbol files nest under
+  `Namespaces` are read as well.
+- The handbook in German: `--language de` (`handbook.language`). The terms
+  follow the German Business Central client, and the app and the VS Code
+  panel switch between English and German.
+- `bca export --view report --handbook` (`report.handbook`) adds the handbook
+  to the report, linked to the catalog with `--codegraph`. The new MCP tool
+  `bc_atlas_handbook` lets agents read it.
+- `bca architecture --explain <object>` and **Why in …** on the app's object
+  page explain where an object belongs: the selector that assigns it and its
+  coupling to each component.
+- The app edits what the proposal considers. **Keep component** and
+  **Release component** change `architecture.proposal.keep`; **Exclude from
+  shaping** and **Shape components again** change `architecture.proposal.exclude`.
+- `bca check` has quality rules that read the objects' metadata:
+  - `missing-data-classification` and `obsolete-without-tag` (warning)
+  - `high-complexity` above `check.maxComplexity`, default 25 (warning)
+  - `missing-tooltip`, `obsolete-without-reason`, and
+    `undocumented-public-api` (info)
+
+  Each rule reports once per object, and `check.severities` sets it to
+  error, warning, info, or off. On Microsoft's System Application they find 17
+  public codeunits with undocumented procedures and 5 codeunits with
+  procedures above complexity 25, and no false positives in the samples
+  checked against the source.
+- Event subscriber relations record the event they subscribe to (`event` on
+  `subscribes` edges).
+- Objects, fields, and procedures carry `metadata` that describes what they
+  are. The values are normalized from the AL source:
+  - from `///` documentation comments: the summary text
+  - from properties: caption and translator comment, access, extensible,
+    obsolete state, reason, and tag, and data classification
+  - the object's kind: page, table, and query type, subtype, source table,
+    `TableNo`, usage category, application area, and API
+  - permissions and inherent permissions
+  - size: lines, fields, keys, procedures, triggers, events, actions
+  - cyclomatic complexity per procedure, plus total and maximum per object
+
+  The object catalog has an **Overview** section, and its procedure tables add
+  lines, complexity, and descriptions. Tables and pages list their procedures
+  and triggers too. The app's object page has an **About** card. The knowledge
+  graph exports documentation, obsolete state, data classification, page type,
+  line count, and complexity.
+
+### Fixed
+
+Found by running BC Atlas on Microsoft's System Application source (1,345
+files) and on the real Base Application 29 symbols:
+
+- Symbol packages:
+  - objects nested under `Namespaces` are read (with #85); before, almost
+    every object of the Base Application was missing
+  - enums (`EnumTypes`, `EnumExtensionTypes`), profiles, profile extensions,
+    and control add-ins load too
+  - page field counts read the numeric control kinds, action counts include
+    the actions inside groups, and local methods count as local
+  - a page's source table is named instead of given by ID, and application
+    areas lose their `#`
+- An object that refers to itself (a variable of its own type) is no longer
+  reported as a dependency cycle.
+- The architecture proposal keeps an app or module whose objects have no
+  relations to each other (a module of only permission sets or control
+  add-ins) as one component named after it, not "Unconnected". Permission
+  sets the relations leave unconnected join the component, within their own
+  app or module, that holds most of the objects they grant.
+- The handbook's documentation coverage counts only public procedures of
+  public objects (the API other apps can call); on the System Application,
+  96% instead of a misleading 47%.
+- The handbook with `--catalog` analyzes the project once instead of twice.
+- `///` summaries are found above `#pragma` and other preprocessor lines,
+  as the System Application writes them.
+
+- Knowledge graph captions no longer include `Comment = ...` and other options
+  of the Caption property. `bca:access` now comes from the `Access` property of
+  every object, not only permission sets.
+- The object catalog's global-variable table no longer has a Properties column
+  that was always empty.
+- The AL compiler no longer fails with AL1018 ("Directory could not be
+  found") on every run: assembly probing folders that do not exist, such as
+  the AL default `./.netpackages` that VS Code reports even when it is
+  absent, are left out of the call, as package cache folders already were.
+- VS Code: symbols that the AL Language extension resolves are found by BC
+  Atlas too. The extension passed the AL defaults (`./.alpackages`,
+  `./.netpackages`) of settings nobody set, and these overrode every
+  project's own `.vscode/settings.json` and the `.code-workspace` settings,
+  so a `al.packageCachePath` such as `../symbols` was ignored and the
+  compiler and the symbol loader reported missing packages. Now only values
+  someone set are passed, by layer (user, workspace, workspace folder), and a
+  project's own settings win, as in VS Code.
+- The explorer timeline loads symbols from the configured `al.packageCachePath`
+  too, not only from `.alpackages`.
+- A rule set or analyzer that does not exist no longer stops the compile:
+  it is left out and reported as `al-ruleset-missing` or
+  `al-analyzer-missing` next to `app.json`. A toolchain without an analyzer
+  folder skips code analysis instead of failing the whole run.
+- `al.*` path settings expand `${workspaceFolder}`, `${userHome}`,
+  `${env:NAME}`, and `~`, as VS Code does; before, such a path pointed nowhere.
+  In VS Code, `${workspaceFolder}` is the editor's workspace folder.
+
+### Changed
+
+- The BC Atlas GitHub Action (new `cache` input, on by default) and the
+  workflows and pipelines that `bca setup` writes keep the BC Atlas cache
+  folder between runs (`actions/cache`, Azure `Cache@2`), so CI benefits from
+  the parse and layout caches too. Generated GitHub workflows use
+  `actions/checkout@v7`, `actions/setup-node@v7`, `actions/cache@v6`, and
+  `actions/upload-artifact@v7`.
+- Dependabot also updates the VS Code extension's dependencies.
+- Repeated `bca check`, `bca export`, and `bca run` calls are several times
+  faster with identical output: diagram layouts are cached by their exact
+  content, the CLI reuses the parse results of unchanged files (as VS Code
+  already did), and views no longer deep-copy the analyzed model. On a
+  synthetic 390-file app, a warm `bca export --view report` takes 0.5 instead
+  of 5.1 s, a project diagram 0.4 instead of 3.7 s, and `bca check` 0.4
+  instead of 1.2 s. `BCA_LAYOUT_CACHE=off` and `BCA_PARSE_CACHE=off` turn the
+  caches off.
+- `scripts/benchmark.js` (`npm run benchmark`) generates a synthetic app and
+  times commands cold and warm.
+- `bca --version`, help, and usage errors start in about 50 instead of 280 ms:
+  command modules load only when their command runs.
+- Faster 3D explorer and architecture proposal; on a 2,800-object app with a
+  Base-Application-sized symbol package, the explorer opens in 0.4 instead of
+  2.3 s and a proposal takes 0.4 instead of 1.3 s, with identical results:
+  - symbol packages are unzipped and parsed once per file version instead of
+    for every page;
+  - the explorer and the architecture pages reuse the app's analyzed model
+    instead of analyzing or copying it again;
+  - `object:` selectors are looked up by name: a proposal has one per
+    misplaced object, and each was tested against every object of the model;
+  - AL names are normalized once.
+- A failed compile without any symbol package reports one
+  `al-symbols-missing` hint ("Run AL: Download Symbols") next to `app.json`.
+
+## 0.15.0 - 2026-11-05
+
+### Added
+
+- Saved graphs are a reusable platform: analyze once, query repeatedly, and
+  render for a specific use case without re-analyzing AL.
+- `bca graph query` and the MCP tool `bc_atlas_graph_query` select roots,
+  named root groups, traversal depth, dependency or caller direction,
+  relation kinds, graph levels, and temporal presence frames. Native Atlas
+  graphs and version 1 nodes/edges snapshots retain their original IDs,
+  evidence, unresolved boundaries, and metadata in reusable JSON slices.
+- `bca graph render` and `bc_atlas_graph_render` write SVG, self-contained
+  static HTML, Graphviz DOT, or JSON. SVG and HTML use the existing local
+  renderer without requiring Graphviz; roots are highlighted and every
+  selected node and edge is retained.
+- Graph validation rejects unsupported versions, invalid roots, and missing
+  endpoints, prevents overwriting the input, and rejects oversized visual
+  selections explicitly rather than truncating dependencies.
+
 ## 0.14.0 - 2026-11-05
 
 ### Added

package/README.md

@@ -15,7 +15,8 @@ BC Atlas (`bca`) parses AL with
 objects, calls, events, data access, and permissions into an architecture
 model, and shows it in one app: overview, health, a target architecture with
 the work to reach it, a 3D dependency explorer, diagrams, one page per object,
-and documentation from UI tests. The same results are files for Git and CI.
+a system handbook, and documentation from UI tests. The same results are
+files for Git and CI.
 Parser and renderer are WebAssembly: Node.js is the only requirement.
 
 **Documentation: [schulzoli.github.io/BC-Atlas](https://schulzoli.github.io/BC-Atlas/)**
@@ -26,6 +27,7 @@ cd path/to/al-project
 bca setup                   # .bca.json, Husky hooks, VS Code tasks, pipeline, schedule (or: bca setup agent)
 bca check                   # architecture gate for CI
 bca export --view report    # docs/atlas/README.md: overview, diagrams, health
+bca export --view handbook  # docs/handbook: events, data, permissions, UI, code health
 bca update                  # new version? see what changed and update everything in one step
 ```
 
@@ -37,14 +39,17 @@ In VS Code, install the **BC Atlas** extension and open an AL project:
 
 | Area | Command | What you get |
 | --- | --- | --- |
-| **In VS Code** | BC Atlas extension | Everything below in the editor: a panel with overview, health, architecture, 3D dependencies, diagrams, objects, and docs; findings in the Problems panel; CodeLens above AL objects; the MCP server for agents. [Guide](./docs/vscode.md) |
+| **In VS Code** | BC Atlas extension | Everything below in the editor: a panel with overview, health, architecture, 3D dependencies, diagrams, objects, the handbook, and docs; findings in the Problems panel; CodeLens above AL objects; the MCP server for agents. [Guide](./docs/vscode.md) |
 | **Get started** | `bca setup` | Guided setup in the terminal or through your AI agent (Claude Code, Copilot, Cursor): a starter `.bca.json`, features, Husky or Git hooks, GitHub Actions or Azure Pipelines, cron schedule, and sync. |
-| **Analyze** | `bca check` | Health findings - cycles, forbidden dependencies, architecture violations, hot spots, diagnostics, and AL compiler and CodeCop/UICop/AppSourceCop findings - with a CI exit code, also as SARIF for code scanning. |
-| | `bca architecture` | Find a target architecture (components, layers), list every dependency that blocks it with how to resolve it, and enforce it with a shrinking baseline. [Guide](./docs/clean-architecture.md) |
+| **Analyze** | `bca check` | Health findings - cycles, forbidden dependencies, architecture violations, hot spots, missing DataClassification or ToolTips, obsolete markings without a tag, complex procedures, undocumented public API, diagnostics, and AL compiler and CodeCop/UICop/AppSourceCop findings - with a CI exit code, also as SARIF for code scanning. [Rules](./docs/health-checks.md) |
+| | `bca architecture` | Find a target architecture (components, layers), list every dependency that blocks it with how to resolve it, and enforce it with a shrinking baseline. You decide what the proposal considers (`architecture.proposal`: relation kinds, starting structures, granularity, components you keep, objects you exclude), it says how it was made, and `--explain` says why an object is where it is. [Guide](./docs/clean-architecture.md) |
+| | `bca graph query` | Reuse a saved graph for impact analysis or message migrations without re-analyzing AL; keep IDs, directions, evidence, and metadata. [Guide](./docs/dependency-explorer.md#query-and-render-saved-graphs) |
 | **Export** | `bca export` | Everything the extension shows, as files: the BC Atlas pages as one offline HTML file to share (default), the Markdown report ([example](./examples/report/README.md)), the 3D explorer, one Markdown page per object, any of ten diagram views as D2, SVG, PNG, PDF, or JSON, with `--watch`, and the project as a knowledge graph in RDF with an OWL ontology ([Turtle, RDF/XML, OWL, N-Triples, JSON-LD](./docs/knowledge-graph.md)). |
+| | `bca export --view handbook` | The system handbook: what the app consists of, its events, data (who inserts, modifies, deletes, reads each table), permissions, interfaces, user interface, and code health, across all objects, in English or German, linked to the object catalog. [Guide](./docs/handbook.md), [example](./examples/handbook/README.md) |
 | | `bca docs` | User guides and test cases from AL UI tests (`[SCENARIO]`, `[GIVEN]`, `[WHEN]`, `[THEN]`) as Markdown, HTML, DITA 1.3, or Azure DevOps CSV, with real captions and translations, a flow diagram per scenario, and BPMN 2.0 processes per use case. [Example](./examples/docs/index.md) |
+| | `bca graph render` | Render saved graph selections as SVG, static HTML, DOT, or JSON through the CLI or MCP, locally and without Graphviz. |
 | **Integrate** | `bca run` | One entry point for Git hooks, schedules, and pipelines; verifies, stages, or publishes generated files. Also available as a [GitHub Action](./docs/automation-and-ci.md#github-actions). |
-| | `bca update` | "BC Atlas 0.14.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
+| | `bca update` | "BC Atlas 0.16.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
 | | `bca mcp` | A Model Context Protocol server for AI agents; `bca help --format json` is the versioned command contract. |
 
 Run `bca` for the same overview in your terminal and `bca help <command>` for
@@ -123,6 +128,10 @@ Generated from the checked-in [warehouse example](./examples/README.md).
 - permission sets: table-data `RIMD` rights, execute rights, and composed sets
   across dependent apps;
 - pages, parts, actions, and navigation;
+- what characterizes each object, field, and procedure: captions, `///`
+  summaries, access, obsolete state, data classification, page and table
+  types, size, and cyclomatic complexity, also for objects in symbol
+  packages;
 - `app.json` metadata, `.alpackages` symbols and `al.packageCachePath`,
   `.code-workspace` multi-root workspaces, cycles, hubs, orphans, and
   unresolved references.
@@ -180,10 +189,10 @@ search, or browse them here, starting with the [table of contents](./docs/_TOC_.
 - [Architecture reports](./docs/reports.md) and [health checks](./docs/health-checks.md)
 - [Architecture diagrams and views](./docs/architecture-diagrams.md)
 - [Configuration](./docs/configuration.md) and the complete [`.bca.example.json`](./.bca.example.json)
-- [Documentation from AL UI tests](./docs/al-ui-test-documentation.md) and [Code Graph](./docs/code-graph-markdown-design.md)
+- [System handbook](./docs/handbook.md), [documentation from AL UI tests](./docs/al-ui-test-documentation.md), and [Code Graph](./docs/code-graph-markdown-design.md)
 - [Agent integration and MCP](./docs/agent-integration.md)
 - [CLI reference](./docs/cli-reference.md) and [troubleshooting](./docs/troubleshooting.md)
-- Generated examples: [architecture report](./examples/report/README.md) and [user guides](./examples/docs/index.md)
+- Generated examples: [architecture report](./examples/report/README.md), [system handbook](./examples/handbook/README.md), and [user guides](./examples/docs/index.md)
 
 ## AI agents and tools
 
@@ -194,8 +203,8 @@ bca mcp                  # MCP stdio server (also installed as bca-mcp)
 
 Agents should read the contract first, pass arguments as arrays, parse stdout
 only after a successful exit code, and preview changes with `--dry-run`. The
-MCP server exposes inspect, check, report, diagram, documentation, setup, run,
-and update-check tools. `bca setup agent --agent claude|copilot|cursor` adds a
+MCP server exposes inspect, check, architecture, report, handbook, diagram,
+documentation, setup, run, and update-check tools. `bca setup agent --agent claude|copilot|cursor` adds a
 `/bca-setup` command that lets your agent guide the setup. See
 [agent integration](./docs/agent-integration.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bc-atlas",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "BC Atlas maps Microsoft Dynamics 365 Business Central AL projects: architecture diagrams, health checks, reports, and documentation generated from source.",
   "homepage": "https://github.com/SchulzOli/BC-Atlas#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "src/",
     "vendor/",
+    "schemas/",
     ".bca.example.json",
     "CHANGELOG.md",
     "LICENSE",
@@ -31,6 +32,7 @@
     "docs": "node ./scripts/generate-docs.js",
     "docs:check": "node ./scripts/generate-docs.js --check",
     "examples": "node ./scripts/generate-examples.js",
+    "benchmark": "node ./scripts/benchmark.js",
     "mcp": "node ./src/mcp.js",
     "prepack": "npm run check && npm test",
     "update:grammar": "node ./scripts/update-grammar.js",
@@ -81,7 +83,7 @@
     "n3": "^2.13.12",
     "opentype.js": "^2.0.0",
     "rdfxml-streaming-parser": "^3.3.0",
-    "three": "^0.186.1",
-    "vitepress": "2.0.0-alpha.20"
+    "three": "^0.187.0",
+    "vitepress": "2.0.0-alpha.21"
   }
 }

package/schemas/bca.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/SchulzOli/BC-Atlas/blob/main/schemas/bca.schema.json",
+  "title": "BC Atlas configuration (.bca.json)",
+  "description": "Settings for bca check, export, architecture, docs, and run. See docs/configuration.md.",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" },
+    "view": { "description": "Default diagram view.", "enum": ["project", "module", "object", "data", "call", "boundary", "contracts", "events", "ui", "workflow"] },
+    "projectRoot": { "description": "Root of the AL project, relative to this file.", "type": "string" },
+    "paths": { "description": "Analyze only these folders (globs allowed).", "type": "array", "items": { "type": "string" } },
+    "direction": { "enum": ["right", "down", "left", "up"] },
+    "title": { "type": "string" },
+    "groupBy": { "description": "Diagram grouping (not the architecture proposal; see architecture.proposal.groupBy).", "enum": ["namespace", "folder", "type", "role"] },
+    "roleMappings": { "description": "Role lanes for the project view: role name to selectors.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
+    "namespaces": { "type": "array", "items": { "type": "string" } },
+    "include": { "type": "array", "items": { "type": "string" } },
+    "exclude": { "description": "Files to leave out of the analysis (globs).", "type": "array", "items": { "type": "string" } },
+    "moduleDepth": { "oneOf": [{ "const": "auto" }, { "type": "integer", "minimum": 1 }] },
+    "folderDepth": { "type": "integer", "minimum": 1 },
+    "includeUnresolvedCalls": { "type": "boolean" },
+    "maxEdges": { "type": "integer", "minimum": 1 },
+    "details": { "type": "boolean" },
+    "noExternal": { "type": "boolean" },
+    "sourceUrl": { "description": "Link template for source locations: {ref}, {file}, {line}.", "type": "string" },
+    "sourceRef": { "type": "string" },
+    "sourcePathPrefix": { "type": "string" },
+    "workflow": { "type": "object" },
+    "forbiddenDependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "severity": { "enum": ["error", "warning", "info"] },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "architecture": { "$ref": "#/$defs/architecture" },
+    "check": {
+      "type": "object",
+      "properties": {
+        "failOn": { "enum": ["error", "warning", "info", "never"] },
+        "cycles": { "enum": ["error", "warning", "info", "off"] },
+        "maxFanIn": { "type": "integer", "minimum": 1 },
+        "maxFanOut": { "type": "integer", "minimum": 1 },
+        "maxComplexity": { "description": "high-complexity: procedures above this cyclomatic complexity (default 25).", "type": "integer", "minimum": 1 },
+        "severities": {
+          "description": "Severity of the quality rules: error, warning, info, or off.",
+          "type": "object",
+          "properties": {
+            "missing-data-classification": { "enum": ["error", "warning", "info", "off"], "default": "warning" },
+            "obsolete-without-tag": { "enum": ["error", "warning", "info", "off"], "default": "warning" },
+            "high-complexity": { "enum": ["error", "warning", "info", "off"], "default": "warning" },
+            "missing-tooltip": { "enum": ["error", "warning", "info", "off"], "default": "info" },
+            "obsolete-without-reason": { "enum": ["error", "warning", "info", "off"], "default": "info" },
+            "undocumented-public-api": { "enum": ["error", "warning", "info", "off"], "default": "info" }
+          }
+        },
+        "contractExpectations": { "type": "array" },
+        "contexts": { "type": "array" }
+      }
+    },
+    "al": {
+      "type": "object",
+      "properties": {
+        "compiler": { "description": "auto, off, or a path to alc, al, or the AL extension folder.", "type": "string" },
+        "analyzers": { "type": "array", "items": { "type": "string" } },
+        "errorLog": { "type": "string" },
+        "callGraph": { "type": "boolean" },
+        "workspaceFile": { "type": "string" }
+      }
+    },
+    "report": {
+      "type": "object",
+      "properties": {
+        "outputDir": { "type": "string" },
+        "views": { "type": "array", "items": { "type": "string" } },
+        "format": { "enum": ["svg", "d2"] },
+        "title": { "type": "string" },
+        "codegraph": { "type": "boolean" },
+        "handbook": { "description": "Also write the system handbook to <outputDir>/handbook.", "type": "boolean" },
+        "json": { "type": "boolean" }
+      }
+    },
+    "codegraph": { "type": "object", "properties": { "outputDir": { "type": "string" } } },
+    "handbook": {
+      "description": "The system handbook (bca export --view handbook, the handbook task of bca run).",
+      "type": "object",
+      "properties": {
+        "outputDir": { "type": "string", "default": "docs/handbook" },
+        "title": { "type": "string" },
+        "language": { "description": "Language of the pages: en (default) or de (de-DE).", "type": "string" },
+        "catalog": { "description": "Folder of the object catalog that object names link to; bca run uses the codegraph task's folder when the same run writes it.", "type": "string" }
+      }
+    },
+    "docs": { "type": "object" },
+    "automation": { "type": "object" }
+  },
+  "$defs": {
+    "selector": {
+      "description": "namespace:, folder:, file:, app:, module:, type:, object:type:name, id:from..to, or *; join with & so all must match.",
+      "type": "string"
+    },
+    "selectors": {
+      "oneOf": [
+        { "$ref": "#/$defs/selector" },
+        { "type": "array", "items": { "$ref": "#/$defs/selector" }, "minItems": 1 }
+      ]
+    },
+    "relationKind": {
+      "enum": ["writes", "extends", "source", "relates", "implements", "calls", "runs", "part", "reads", "selects", "uses", "subscribes", "permits", "includes"]
+    },
+    "architecture": {
+      "type": "object",
+      "properties": {
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "match"],
+            "properties": {
+              "name": { "type": "string" },
+              "description": { "type": "string" },
+              "layer": { "type": "integer", "minimum": 0 },
+              "match": { "$ref": "#/$defs/selectors" },
+              "dependsOn": { "type": "array", "items": { "type": "string" } },
+              "exposes": { "$ref": "#/$defs/selectors" },
+              "maxObjects": { "type": "integer", "minimum": 1 }
+            }
+          }
+        },
+        "proposal": { "$ref": "#/$defs/proposal" },
+        "couplingWeights": {
+          "description": "How strongly each relation kind binds two objects (defaults: writes 5, extends 4, source 4, relates 3, implements 3, calls 2, runs 2, part 2, reads 2, selects 1.5, uses 1, subscribes 1, permits 0.1, includes 0.1). 0 drops a kind.",
+          "type": "object",
+          "propertyNames": { "$ref": "#/$defs/relationKind" },
+          "additionalProperties": { "type": "number", "minimum": 0 }
+        },
+        "allowSameLayer": { "type": "boolean" },
+        "strictLayers": { "type": "boolean" },
+        "maxObjects": { "type": "integer", "minimum": 1 },
+        "severity": { "enum": ["error", "warning", "info", "off"] },
+        "unassigned": { "enum": ["error", "warning", "info", "off"] },
+        "severities": { "type": "object", "additionalProperties": { "enum": ["error", "warning", "info", "off"] } },
+        "rules": { "type": "array" },
+        "baseline": { "type": "string" },
+        "surface": { "type": "string" }
+      }
+    },
+    "proposal": {
+      "description": "What bca architecture --propose takes into account, and how. Options of the command override these.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$comment": { "type": "string" },
+        "groupBy": {
+          "description": "auto or coupling: the typed, weighted relations decide; namespace or folder: the code structure decides, objects without it follow their relations; module or app: one component each.",
+          "enum": ["auto", "coupling", "namespace", "folder", "module", "app"],
+          "default": "auto"
+        },
+        "depth": { "description": "With groupBy namespace or folder: segments per component; default: split until no component is too large.", "type": "integer", "minimum": 1 },
+        "minObjects": { "description": "Smaller groups join the component they depend on most.", "type": "integer", "minimum": 1, "default": 1 },
+        "startFrom": {
+          "description": "Existing structures that compete with the relations as a starting point. [] for relations only. The relations decide which survives.",
+          "type": "array",
+          "items": { "enum": ["namespace", "folder"] },
+          "uniqueItems": true,
+          "default": ["namespace", "folder"]
+        },
+        "ignore": {
+          "description": "Relation kinds that never shape a component (they still count as dependencies).",
+          "type": "array",
+          "items": { "$ref": "#/$defs/relationKind" },
+          "uniqueItems": true,
+          "default": ["permits", "includes"]
+        },
+        "granularity": { "description": "Above 1: more, smaller components; below 1: fewer, larger ones.", "type": "number", "exclusiveMinimum": 0, "default": 1 },
+        "appGranularity": { "description": "The same for app candidates (which components could become one app together).", "type": "number", "exclusiveMinimum": 0, "default": 0.3 },
+        "sharedCore": { "description": "Pull objects that many components use (setup tables, utilities) into a shared core.", "type": "boolean", "default": true },
+        "keep": {
+          "description": "Components you define yourself. Their objects are not clustered; the proposal arranges everything else around them.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "match"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "match": { "$ref": "#/$defs/selectors" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "exclude": {
+          "description": "Objects that do not shape components (for example type:permissionset or test codeunits). They join the component they are most coupled to afterwards.",
+          "$ref": "#/$defs/selectors"
+        },
+        "moves": {
+          "description": "Objects that belong elsewhere: at least minGain more coupling to another component than to their own; at most limit of them.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "minGain": { "type": "number", "minimum": 0, "default": 2 },
+            "limit": { "type": "integer", "minimum": 0, "default": 50 }
+          }
+        }
+      }
+    }
+  }
+}