bc-atlas 0.7.0 → 0.10.0

package/.bca.example.json

@@ -63,12 +63,52 @@
       "message": "Core must not depend on UI"
     }
   ],
+  "architecture": {
+    "components": [
+      { "name": "Core", "layer": 0, "match": ["namespace:Contoso.Core"], "exposes": ["type:interface,table", "object:codeunit:Core API"] },
+      { "name": "Sales", "layer": 1, "match": ["namespace:Contoso.Sales"], "dependsOn": ["Core"], "maxObjects": 400 },
+      { "name": "Integration", "layer": 2, "match": ["app:Contoso Integration"], "dependsOn": ["Sales"] }
+    ],
+    "allowSameLayer": false,
+    "strictLayers": false,
+    "maxObjects": 1500,
+    "couplingWeights": { "reads": 2, "subscribes": 1 },
+    "severity": "error",
+    "unassigned": "warning",
+    "severities": {
+      "internal-access": "warning",
+      "unstable-dependency": "off"
+    },
+    "rules": [
+      {
+        "name": "owner-writes-its-tables",
+        "from": "*",
+        "to": "type:table",
+        "kinds": ["writes"],
+        "across": true,
+        "severity": "error",
+        "message": "Only the component that owns a table writes to it",
+        "resolution": "Call a codeunit of the owning component that writes the record."
+      },
+      {
+        "name": "core-has-no-ui",
+        "from": "layer:0",
+        "to": "type:page,report",
+        "except": ["object:page:Core Setup"]
+      }
+    ]
+  },
   "check": {
     "failOn": "error",
     "cycles": "warning",
     "maxFanIn": 25,
     "maxFanOut": 25
   },
+  "al": {
+    "compiler": "auto",
+    "analyzers": ["CodeCop", "UICop"],
+    "callGraph": true
+  },
   "report": {
     "outputDir": "docs/atlas",
     "views": [

package/CHANGELOG.md

@@ -4,7 +4,331 @@ 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/).
 
-## Unreleased
+## 0.10.0 - 2026-10-29
+
+The npm package skips 0.9.0 so it shares its version with the VS Code
+extension, whose previous release was 0.9.0.
+
+### Added
+
+- Shared core: objects that many components use but none owns (setup
+  tables, master data) form a component of their own instead of gluing the
+  others together.
+- App candidates and namespaces: components that are coupled more to each
+  other than to the rest could become one app together. Every proposed
+  component gets a role (app, component, shared core) and a suggested
+  namespace, in the JSON (`proposal.recommendations`), the reports, the
+  component's description, and the Architecture page.
+- `id:50100..50199` selects objects by ID range; proposals use it for code
+  without namespaces or functional folders.
+- A page per component (click it on the Architecture page): its role, layer,
+  the components it may use, suggested namespace, app candidate, and
+  selectors; the groups inside it (sub-domains clustered by coupling and
+  named after their namespace, folder, or shared words); a graph of its
+  objects with one island per group and, on request, its links to other
+  components in green (allowed) and red (wrong way); per other component
+  whether it may be used and how often it is; every object; and its work
+  items. Also in the exported app.
+- Dependencies between components, should vs. is: a map of the components in
+  their layers with green arrows for allowed and red arrows for wrong-way
+  dependencies, and a matrix that tints every pair by the rules and counts
+  today's object links in it.
+- `bca docs` turns more TestPage code into steps: `Field.Value :=`,
+  `Filter.SetFilter`, `GoToKey`, the `OK`, `Cancel`, `Yes`, and `No` buttons,
+  `First`/`Last`/`Next`/`Previous`, `Lookup`, `Drilldown`, `AssistEdit`,
+  `Page.Trap()` ("The ... page opens."), `asserterror` ("Business Central
+  shows an error message."), calls over several lines, and the pages and
+  confirmations a test answers in `[ModalPageHandler]`, `[PageHandler]`,
+  `[RequestPageHandler]`, and `[ConfirmHandler]` procedures ("If the ... page
+  opens, ...").
+
+### Changed
+
+- The architecture proposal comes from the relations, not from namespaces.
+  Relations are typed (structural, data, behavioral, loose, administrative)
+  and weighted; inside each app or module, the objects that are coupled more
+  to each other than to the rest form a component (the best of several
+  Louvain runs, refined object by object, with today's namespaces and
+  folders competing as candidates). It works the same for apps without
+  namespaces (type folders, ID blocks) and for a mix. `--group-by coupling`
+  is now the same as `auto`; `namespace` and `folder` let the structure
+  decide and place objects without one by their relations.
+- A page or query and its source table are a relation of their own
+  (`source`, weight 4) instead of a read.
+- VS Code and `bca export --view app` keep the parse results of every AL file
+  on disk (`BCA_CACHE_DIR`, default `<temp>/bc-atlas/parse`) and across
+  changes, so reopening a project or saving a file parses only what changed.
+  The Docs page and the explorer reuse them instead of parsing the app again.
+  On a 2,931-object app the overview opens in about 8 seconds instead of 15,
+  and the Docs page in about 11 instead of 25.
+- The npm package and the VS Code extension are released under one version
+  number from now on, starting with 0.10.0; `npm run version:set -- <version>`
+  sets both, and the tests and publish workflows refuse a mismatch.
+- Dependencies: zod 4.6.7, web-tree-sitter 0.27.1, and the MCP SDK 2.4.0.
+
+### Fixed
+
+- The report no longer writes an absolute path into README.md when a view has
+  too many nodes for the bundled SVG renderer: it keeps the view as D2, links
+  it relative to the README, removes an SVG left by an earlier run, and the
+  MCP report tool marks it `d2Only`.
+- Opening a scenario or use case on the Docs page no longer leaves the page
+  blank in VS Code (or loads the whole app into the frame in an exported
+  app): the guide is embedded through `srcdoc`, where `#links` resolve
+  against the host page, so it now scrolls to the target itself.
+- `bca docs` reads AL tests written the way Microsoft writes the Business
+  Central tests: `[SCENARIO 218101]` with a work item number (kept as a
+  reference), `[FEATURE] [Sales] [Invoice]` lists (`[UI]` and `[UT]` are left
+  out), the codeunit's `[FEATURE]` in its `OnRun` trigger, and `[VERIFY]` as
+  an expected result. Such test codeunits used to give no scenarios at all.
+- A documented test ends where its procedure ends: tags and TestPage calls of
+  helper procedures after it (and, for the last test, the codeunit's global
+  variables) no longer leak into its guide and its fingerprint.
+- Directory runs of `bca docs` leave out `[SCENARIO]` tests without any UI
+  step (unless they have a `[DOC-ID]`) and report how many; they used to
+  become empty guides.
+- Guides for descriptive scenarios ("Users can post ...") no longer read
+  "Use this guide to users can ...", empty values no longer show as `****`,
+  the note about example values only appears when the steps show any, and
+  test case tables keep the context of loops and dialogs in one row.
+
+## 0.8.0 - 2026-10-29
+
+### Added
+
+- Coupling weights: every dependency weighs what it takes to cut it
+  (`writes` 5, `extends` 4, `relates`/`implements` 3, calls and reads 2,
+  subscribers 1, permission grants 0.1; repeats count logarithmically;
+  `architecture.couplingWeights` changes them). The proposal orders
+  components, merges small groups, and finds objects that belong elsewhere
+  by coupling; PageRank and communities use it too.
+- `--group-by coupling`: components from namespaces that are tightly coupled
+  to each other (Louvain communities on the coupling).
+- Every architecture gets a score: cohesion per component, the share of the
+  coupling inside components, and modularity, to compare groupings.
+- Dependency explorer: in open space, what drifts together follows the
+  color (apps, components, communities, types, build layers), groups are
+  spread apart, and tightly coupled objects sit closer together.
+- Dependency explorer: the new default layout **Open space** lets the graph
+  float freely in a large space, like the large-graph example of
+  3d-force-graph: small nodes, hairline links, apps or components that only
+  drift together, and the camera frames the connected objects once the layout
+  has settled. The filters start collapsed (☰ or `F`) so the graph has the
+  whole window.
+- Tools to split a monolith into apps (see the new guide
+  [Split a monolith into apps](./docs/modularization.md) and the example
+  `examples/monolith`):
+  - **Data ownership:** for every table that other components use, who
+    owns, writes, reads, relates to, and extends it; `bca check` reports
+    tables other components write (`foreign-table-write`).
+  - **Extraction plans:** `bca architecture --extract <component>` (and the
+    MCP tool `bc_atlas_extraction_plan`, and the Architecture page) lists what
+    moves, the blockers with their work items (including app cycles), the new
+    app's `app.json` with a stable ID, dependencies, and `idRanges`, the tables
+    whose data moves with `ObsoleteState = PendingMove`/`MovedTo`/`MovedFrom`,
+    and the steps in order.
+  - **Public surface:** per component, the objects other components use (its
+    de facto API) and the objects that could be `Access = Internal`
+    (`could-be-internal`). `bca refactor surface` (and MCP
+    `bc_atlas_refactor_surface`) sets `Access = Internal` on them and writes
+    the API to `exposes`. `bca architecture --update-surface` records the
+    surface in `.bca-surface.json`; `bca check` then reports changes that
+    break its users, like AppSourceCop for internal boundaries
+    (`public-surface-change`: removed or internal objects, changed procedure
+    signatures, removed events, fields, and enum values).
+  - **`bca refactor move`:** moves an AL object to another component: its
+    file, or the object cut out of a shared file, goes to the component's
+    folder, its namespace becomes the component's, and referencing files get
+    the `using` they need. Dry run by default; also the MCP tool
+    `bc_atlas_refactor_move`. Work items that are moves carry the command.
+- VS Code: the extension and its engine are bundled with esbuild; the
+  `.vsix` holds about 50 instead of 1,200 files, and CI tests the packaged
+  extension.
+- More architecture rules in `bca check`, `bca architecture`, and the
+  Architecture page:
+  - **Public objects:** a component may use only public objects of another
+    one: `internal-access` for objects with `Access = Internal` (no other app
+    can see them) or outside the component's new `exposes` selectors.
+  - **Strict layers:** `strictLayers` lets a component use only the layer
+    directly below it (`layer-skip-dependency`).
+  - **Rules of your own:** `architecture.rules` forbids dependencies by
+    selectors, now also `component:` and `layer:`, with relation `kinds`
+    (e.g. only `writes`), `except`, `across`, and a message and resolution
+    (`dependency-rule`). Its violations are baselined like the others.
+  - **Checks of the architecture:** empty components, unused selectors, unused
+    or layer-contradicting `dependsOn` entries, declared cycles, components
+    above `maxObjects`, and dependencies on less stable components. Checks of
+    the configuration point at the component in `.bca.json`.
+  - **Severities:** `architecture.severities` sets the severity of each rule
+    or turns it off.
+  - New strategies `use-public-api`, `go-through-layer`, and `follow-rule`;
+    the report counts violations by rule.
+- VS Code: the BC Atlas panel takes its design from the editor's color theme
+  (background, text, borders, accent, selection, status colors, and fonts),
+  for any theme including high contrast; the 3D explorer and the Docs page
+  inside the panel follow too. Exported pages keep the BC Atlas design.
+- VS Code: the BC Atlas side bar is the panel's navigation and marks the page
+  it shows; the panel no longer repeats the pages in a navigation of its own.
+- Microsoft's AL toolchain replaces BC Atlas's own analysis where it knows
+  better. With the AL Language extension or the AL Development Tools
+  installed (`al.compiler: auto`, the default), BC Atlas compiles a copy of the
+  workspace in dependency order and:
+  - resolves calls with the compiler's call graph (`al graph`): overloads,
+    variables, interfaces, and built-in methods, which no longer show up as
+    unresolved calls;
+  - reports compiler errors and warnings and CodeCop, UICop, AppSourceCop, and
+    PerTenantExtensionCop findings in `bca check`, with exact ranges and help
+    links; compiler syntax errors replace tree-sitter parse errors.
+
+  Results are cached by file content; nothing is written into the repository.
+  `--compiler auto|off|<path>`, `BCA_AL_COMPILER`, and the `al` section of
+  `.bca.json` choose the compiler; `--analyzers CodeCop,UICop` picks analyzers.
+- `bca check --compiler-log <file|folder>` imports AL compiler error logs from
+  any build (alc `/errorlog`, `al workspace compile --errorlogdirectory`,
+  AL-Go, BcContainerHelper) without a compiler on the machine.
+- `bca check --format sarif`: SARIF 2.1.0 with BC Atlas and AL findings for
+  GitHub code scanning and Azure DevOps.
+- AL settings like the AL Language extension reads them: `al.packageCachePath`
+  (string or list) for symbols, `al.codeAnalyzers` with
+  `al.enableCodeAnalysis`, `al.ruleSetPath`, and `al.assemblyProbingPaths`
+  from `.vscode/settings.json` and `.code-workspace` files, whose `folders`
+  also define the projects. The same symbol package in several caches loads
+  once.
+- VS Code: the extension uses the AL Language extension's compiler and the
+  editor's `al.*` settings, compiles in the background after each change, and
+  analyzes again after **AL: Download Symbols**, a new `.app`, or changed AL
+  settings. Settings `bcAtlas.alCompiler` and `bcAtlas.alAnalyzers`. Compiler
+  findings in the Problems panel are left to the AL Language extension.
+- Generated GitHub Actions workflows and Azure Pipelines, and the BC Atlas
+  GitHub Action (`al-compiler` input), install the AL Development Tools.
+- BC Atlas for VS Code (`vscode/`, `SchulzOli.bc-atlas`): everything BC Atlas
+  does, in the editor, with the engine inside. A panel with one look and feel
+  for all of it: an overview, health findings, the architecture (layers, work
+  items, components; adopt a proposal or accept violations with one click),
+  the 3D dependency explorer, diagrams for every view with zoom and pan, a
+  searchable object list with one page per object (dependencies, members,
+  violations; open the source at its line), and the UI-test documentation.
+  Findings in the Problems panel, CodeLens above AL objects, a status bar
+  item, a side bar, commands for export, documentation, setup, and tasks,
+  and the BC Atlas MCP server for agents in VS Code. The engine analyzes in
+  a background process and the panel refreshes when AL files change.
+  `bca setup --editor vscode` recommends the extension.
+- `bca export`: one command for every file output. `--view app` (default)
+  writes the BC Atlas pages as one offline HTML file to share or publish from CI;
+  `report`, `explorer`, `catalog`, and the ten diagram views write what the
+  former commands wrote; `--watch` writes again on every change.
+- The Git timeline can step by merged pull request (`--history-by prs`:
+  GitHub, Azure DevOps, GitLab, and squash merges, with the number of commits
+  each brought) or by release tag (`--history-by releases`, plus unreleased
+  commits); `--last n` keeps the most recent steps. The Dependencies page in
+  VS Code has the same choice.
+- Explorer: a Spacing slider (50 % to 500 %) gives crowded graphs room:
+  longer links, longest between large nodes, stronger repulsion, and more
+  distance between clusters and floors.
+- One design system (`src/ui/theme.css`) for the VS Code panel, the explorer, and the
+  HTML documentation, with light and dark themes.
+
+- `bca architecture`: clean architecture for AL apps. Define components
+  (namespace, folder, app, module, type, or object selectors), layers, and
+  allowed dependencies in `.bca.json`, or let BC Atlas propose them from
+  today's dependencies (`--propose`, weighted feedback arc set and layering).
+  Every dependency that points outward, sideways, or undeclared becomes a work
+  item with a resolution strategy in AL terms: declare the dependency, move an
+  extension, subscriber, permissions, or navigation, move a related field into
+  a table extension, move an object, or invert the dependency with an
+  interface or event. Reports instability, abstractness, and distance per
+  component and which components can become apps of their own; text,
+  Markdown with a Mermaid diagram, and JSON.
+- `--write` saves the architecture to `.bca.json`; `--update-baseline`
+  accepts today's violations. `bca check` fails on new violations, reports
+  fixed ones so the baseline only shrinks, and warns about component cycles.
+- The dependency explorer shows the architecture: a Components level, violating edges
+  in red with their resolution, an Architecture panel with the largest work
+  items, violations per commit on the timeline, and architecture layers as a
+  layout. The MCP server offers `bc_atlas_architecture`.
+
+- Dependency explorer (`bca export --view explorer`, and the Dependencies
+  page in VS Code): an interactive 3D dependency explorer in one
+  self-contained, offline HTML file. Dependencies inside one app are kept apart from
+  dependencies across apps, which are checked against `app.json`: `declared`,
+  `implicit` (Microsoft apps), `undeclared`, and `unresolved`. Switch between
+  an object level and an app level; filter by app, dependency class, object
+  type, and relation kind; search, isolate neighborhoods, and inspect the
+  evidence behind every edge.
+- `--history` replays Git history as a fourth dimension: one frame per commit
+  that changed AL files or `app.json`, with added, changed, and removed
+  objects highlighted. Without Git, the timeline replays the build order.
+- `--format json` writes the `bc-atlas.graph` document: a temporal graph with
+  presence spans, PageRank, Louvain communities, build layers, and cycles,
+  built with graphology. The MCP server offers it as `bc_atlas_explore`.
+- `examples/multi-app`, a three-app workspace, and its explorer example.
+- Nested `app.json` files are modules of the enclosing app, as in BCApps'
+  System Application and Base Application. The explorer adds a module level,
+  checks module dependencies against the module manifests, and marks
+  dependencies between modules of one app as `cross-module`.
+- Platform system objects (`Integer`, `Date`, `Field`, `AllObjWithCaption`,
+  `Company`, ...) and `System "..."` permissions count as implicit
+  dependencies instead of unresolved ones.
+- `--paths` analyzes and replays only some folders of a large
+  repository. Large explorer files embed their graph gzip-compressed and start
+  on the module level.
+
+- `bca docs generate` draws every scenario as a flow of its clicks in BPMN
+  notation ("At a glance"): user tasks, milestones for `[THEN]` between
+  `[WHEN]` phases, loop markers for repeated blocks, and wrapping rows for long
+  flows.
+- Every use case gets a process diagram with one lane per permission set, the
+  scenarios in `[NEXT]`/`[REQUIRES]` order, and an exclusive gateway where
+  `[ALTERNATIVE]` paths branch. In HTML, each scenario links to its guide.
+- `--export bpmn`: `use-case-<feature>.bpmn`, a BPMN 2.0 file with diagram
+  layout and colors for Camunda Modeler, bpmn.io, and Signavio. Each scenario
+  is a collapsed sub-process; double-click it to see its clicks as user tasks.
+
+### Changed
+
+- `internal-access` is on by default: a configured architecture can report
+  new violations where a component uses an `Access = Internal` object of
+  another one. Accept them with `bca architecture --update-baseline`, or set
+  `"severities": { "internal-access": "off" }` when components are layers of
+  one app that never split.
+- The *Publish VS Code extension* workflow signs in to the Marketplace with
+  Microsoft Entra ID (GitHub OIDC, `vsce --azure-credential`) instead of the
+  `VSCE_PAT` token, because Azure DevOps retires global personal access
+  tokens on December 1, 2026. It needs the secrets `AZURE_CLIENT_ID` and
+  `AZURE_TENANT_ID` and checks access to the publisher before publishing.
+- A new BC Atlas icon and logo (an "A" drawn as a dependency graph with an
+  orbit), used by the extension, its activity bar, and the panel. The
+  extension has a Marketplace listing with screenshots, a banner, and a social
+  preview image; sources and the render script are in `vscode/marketing/`.
+- Fewer commands: 8 instead of 15. `bca report`, `bca graph`, `bca watch`,
+  `bca inspect`, and `bca codegraph` are now `bca export --view report`,
+  `--view <view>`, `--watch`, `--format json`, and `--view catalog`; `-o`
+  replaces `--output-dir`. `bca init` is part of `bca setup`, and
+  `bca capabilities` is `bca help --format json`. `bca <app-root>` is no
+  longer a shortcut; the interactive views are in the VS Code extension. See
+  the table in the CLI reference.
+- The journey diagram shows each scenario with its permission set and number
+  of steps. `[NEXT]` and `[REQUIRES]` between the same scenarios are one
+  arrow in flow direction; `[ALTERNATIVE]` and `[RELATED]` are dashed lines.
+
+### Fixed
+
+- The warehouse example declares `using BCA.Example.UI;` for the page its
+  permission set grants; the AL compiler reported it as missing.
+- The 3D explorer inside the panel follows a dark theme: it now asks for the
+  theme once its graph is unpacked, instead of missing the message sent while
+  it was still loading.
+- Namespace-qualified references such as
+  `Record Microsoft.Sales.Document."Sales Header"`,
+  `TableData Microsoft.Sales.Document."Sales Line" = R`, and
+  `Database::Microsoft.Sales.Document."Sales Header"` resolve to their object
+  instead of an unresolved object named `Microsoft`.
+- The call view no longer slows down quadratically on large apps: resolving
+  calls in the Base Application takes about 2.5 instead of 70 seconds.
+
+- Steps on quoted fields and actions, such as
+  `SalesOrder."Sell-to Customer No.".SetValue(...)`, are no longer dropped from
+  generated documentation.
 
 ## 0.7.0 - 2026-10-04
 
@@ -43,9 +367,6 @@ follows [Semantic Versioning](https://semver.org/).
   setup.
 - With a `package.json` that declares `bc-atlas`, generated pipelines and VS
   Code tasks use that version (`npm ci`, `npx --no-install bca`).
-
-### Added
-
 - `bca docs generate` presents scenarios in the structure of an OASIS DITA 1.3
   task topic (prerequisites, steps, step results, result, related links).
   The AL tags are unchanged.

package/README.md

@@ -5,13 +5,17 @@
 [![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![Docs](https://img.shields.io/badge/docs-schulzoli.github.io%2FBC--Atlas-0b62d6)](https://schulzoli.github.io/BC-Atlas/)
 
+![BC Atlas: see your architecture, find what stands in its way, and keep it clean, right in VS Code](./vscode/marketing/social-preview.jpg)
+
 **Understand, guard, and document Microsoft Dynamics 365 Business Central AL
 projects - straight from source.**
 
 BC Atlas (`bca`) parses AL with
 [`tree-sitter-al`](https://github.com/SShadowS/tree-sitter-al), resolves
 objects, calls, events, data access, and permissions into an architecture
-model, and turns it into diagrams, health checks, reports, and documentation.
+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.
 Parser and renderer are WebAssembly: Node.js is the only requirement.
 
 **Documentation: [schulzoli.github.io/BC-Atlas](https://schulzoli.github.io/BC-Atlas/)**
@@ -19,29 +23,29 @@ Parser and renderer are WebAssembly: Node.js is the only requirement.
 ```sh
 npm install --global bc-atlas
 cd path/to/al-project
-bca setup     # features, Husky hooks, VS Code tasks, pipeline, schedule (or: bca setup agent)
-bca report    # docs/atlas/README.md: overview, diagrams, health
-bca check     # architecture gate for CI
-bca update    # new version? see what changed and update everything in one step
+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 update                  # new version? see what changed and update everything in one step
 ```
 
+In VS Code, install the **BC Atlas** extension and open an AL project:
+
+![BC Atlas in VS Code: an object page in the BC Atlas panel next to its AL source with CodeLens and a Problems entry](./docs/generated/images/vscode.png)
+
 ## Features at a glance
 
 | Area | Command | What you get |
 | --- | --- | --- |
-| **Get started** | `bca setup` | Guided setup in the terminal or through your AI agent (Claude Code, Copilot, Cursor): features, Husky or Git hooks, GitHub Actions or Azure Pipelines, cron schedule, and sync. |
-| | `bca init` | A starter `.bca.json`: title, excluded test folders, source links for your Git host. |
-| | `bca report` | One Markdown page with an at-a-glance table, six architecture diagrams, and the health summary. [Example](./examples/report/README.md) |
-| **Visualize** | `bca graph` | D2, SVG, PNG, PDF, or JSON for ten focused views (below). |
-| | `bca watch` | The same diagram, rebuilt on every AL change. |
-| **Analyze** | `bca check` | Health findings - cycles, forbidden dependencies, hot spots, diagnostics - with a CI exit code. |
-| | `bca inspect` | The resolved architecture model as JSON for scripts. |
-| **Document** | `bca codegraph` | One linked Markdown page per AL object. |
-| | `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. [Example](./examples/docs/index.md) |
+| **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) |
+| **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) |
+| **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`. |
+| | `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) |
 | **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.8.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
-| | `bca capabilities` | A versioned JSON contract of every command for tools and agents. |
-| | `bca mcp` | A Model Context Protocol server for AI agents. |
+| | `bca update` | "BC Atlas 0.11.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
 options and examples.
@@ -50,16 +54,52 @@ options and examples.
 
 | View | Answers | Example |
 | --- | --- | --- |
-| `project` | What does the app contain? | `bca graph --view project -o project.svg` |
-| `module` | How do namespaces or folders depend on each other? | `bca graph --view module -o modules.svg` |
-| `object` | What surrounds one object? | `bca graph --view object --object codeunit:50100 -o object.svg` |
-| `data` | Which code reads and writes which tables? | `bca graph --view data -o data.svg` |
-| `call` | Which procedures call each other? | `bca graph --view call --root-procedure Post --call-direction both -o calls.svg` |
-| `boundary` | What crosses a namespace, folder, app, or object boundary? | `bca graph --view boundary --scope namespace:Contoso.Sales -o boundary.svg` |
-| `contracts` | Which types implement an interface? | `bca graph --view contracts -o contracts.svg` |
-| `events` | Which subscribers react to which publishers? | `bca graph --view events --focus OnPosted -o events.svg` |
-| `ui` | How do pages, actions, and source tables connect? | `bca graph --view ui --focus "Sales Order" -o ui.svg` |
-| `workflow` | What happens after an action or entry point? | `bca graph --view workflow --entry action:Release -o flow.svg` |
+| `project` | What does the app contain? | `bca export --view project -o project.svg` |
+| `module` | How do namespaces or folders depend on each other? | `bca export --view module -o modules.svg` |
+| `object` | What surrounds one object? | `bca export --view object --object codeunit:50100 -o object.svg` |
+| `data` | Which code reads and writes which tables? | `bca export --view data -o data.svg` |
+| `call` | Which procedures call each other? | `bca export --view call --root-procedure Post --call-direction both -o calls.svg` |
+| `boundary` | What crosses a namespace, folder, app, or object boundary? | `bca export --view boundary --scope namespace:Contoso.Sales -o boundary.svg` |
+| `contracts` | Which types implement an interface? | `bca export --view contracts -o contracts.svg` |
+| `events` | Which subscribers react to which publishers? | `bca export --view events --focus OnPosted -o events.svg` |
+| `ui` | How do pages, actions, and source tables connect? | `bca export --view ui --focus "Sales Order" -o ui.svg` |
+| `workflow` | What happens after an action or entry point? | `bca export --view workflow --entry action:Release -o flow.svg` |
+
+In VS Code, the Diagrams page of the BC Atlas panel renders every view with zoom and pan.
+
+### Clean architecture
+
+`bca architecture` finds a target architecture for an app or workspace
+(components in layers, dependencies pointing inward), lists every dependency
+that stands in the way as a work item with a concrete resolution (declare it,
+move an extension or subscriber, move a field into a table extension, invert
+it with an interface), and shows which components can become apps of their
+own. Save it to `.bca.json`, accept today's violations in a baseline, and
+`bca check` keeps the architecture from eroding: new violations fail CI,
+fixed ones shrink the baseline. In VS Code, the Architecture page shows the
+layers and work items and adopts a proposal with one click.
+
+```sh
+bca architecture ./app --propose --format markdown -o architecture.md
+bca architecture ./app --propose --write --update-baseline
+bca check ./app
+```
+
+### Interactive dependency explorer
+
+The Dependencies page in VS Code, also written by `bca export --view explorer` as
+one offline HTML file, shows a 3D graph of every AL object and app. Dependencies inside one app stay gray; dependencies across apps are
+checked against `app.json` and colored as declared, implicit (Microsoft),
+undeclared, or unresolved. Filter by app, class, type, or relation kind,
+switch to the app level, and press play: with `--history` the timeline replays
+how objects and dependencies were added, changed, and removed commit by
+commit.
+
+```sh
+bca export ./workspace --view explorer --history -o dependencies.html
+```
+
+![Dependency explorer with three apps, an undeclared cross-app dependency, and the commit timeline](./docs/generated/images/explorer-view.png)
 
 ### Screenshots
 
@@ -83,8 +123,14 @@ 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;
-- `app.json` metadata, `.alpackages` symbols, multi-app workspaces, cycles,
-  hubs, orphans, and unresolved references.
+- `app.json` metadata, `.alpackages` symbols and `al.packageCachePath`,
+  `.code-workspace` multi-root workspaces, cycles, hubs, orphans, and
+  unresolved references.
+
+With Microsoft's AL toolchain installed (the AL Language extension or the AL
+Development Tools), the AL compiler resolves every call and reports compiler
+and code-analyzer findings; BC Atlas's own analysis is the fallback. See
+[AL toolchain](./docs/al-toolchain.md).
 
 Relationship colors are consistent across views, and labels and dash patterns
 ensure that color is never the only signal. Every edge keeps its evidence
@@ -128,7 +174,8 @@ optionally as Dependabot pull requests. See [Guided setup](./docs/setup.md).
 Read the docs at **[schulzoli.github.io/BC-Atlas](https://schulzoli.github.io/BC-Atlas/)**, with
 search, or browse them here, starting with the [table of contents](./docs/_TOC_.md):
 
-- [Getting started](./docs/getting-started.md) and [guided setup](./docs/setup.md), including [staying up to date](./docs/setup.md#staying-up-to-date)
+- [Getting started](./docs/getting-started.md), [BC Atlas for VS Code](./docs/vscode.md), and [guided setup](./docs/setup.md), including [staying up to date](./docs/setup.md#staying-up-to-date)
+- [AL toolchain: compiler, analyzers, AL settings](./docs/al-toolchain.md)
 - [Automation: hooks, schedules, and pipelines](./docs/automation-and-ci.md)
 - [Architecture reports](./docs/reports.md) and [health checks](./docs/health-checks.md)
 - [Architecture diagrams and views](./docs/architecture-diagrams.md)
@@ -141,8 +188,8 @@ search, or browse them here, starting with the [table of contents](./docs/_TOC_.
 ## AI agents and tools
 
 ```sh
-bca capabilities   # versioned JSON contract: argv templates, options, enums, exit codes
-bca mcp            # MCP stdio server (also installed as bca-mcp)
+bca help --format json   # versioned JSON contract: argv templates, options, enums, exit codes
+bca mcp                  # MCP stdio server (also installed as bca-mcp)
 ```
 
 Agents should read the contract first, pass arguments as arrays, parse stdout
@@ -155,26 +202,33 @@ and update-check tools. `bca setup agent --agent claude|copilot|cursor` adds a
 ## How it works
 
 ```text
-*.al + app.json + .alpackages
+*.al + app.json + .alpackages + AL settings
   -> tree-sitter AL syntax tree
   -> objects, members, relations          (analyzer)
+  -> AL compiler: calls and diagnostics   (src/al, when the toolchain is installed)
   -> resolved model with evidence         (resolver, call analysis, semantics)
   -> view projection and insights         (views, workflow, health)
-  -> D2 / SVG / JSON / Markdown           (renderers)
+  -> D2 / SVG / JSON / Markdown / HTML    (renderers)
+  -> the pages: one workspace, in VS Code (vscode/) or exported as one file
 ```
 
 Parsing, resolution, projection, and rendering are separate stages, so new
-views and outputs do not touch the parser. Every command is defined once in
+views and outputs do not touch the parser. The VS Code extension, `bca check`,
+`bca architecture`, and `bca export` read the same analysis, so they always
+agree; `src/ui/theme.css` gives the pages, the explorer, and the HTML
+documentation one look. Every command is defined once in
 `src/capabilities.js`; help, argument validation, the JSON contract, and the
 generated reference derive from it.
 
 ### Current limits
 
-BC Atlas is an architecture extractor, not the AL compiler. References resolve
-by object type, ID, name, namespace, app preference, and declared dependencies,
-including `.alpackages` symbols. Dynamic calls, interface dispatch, and unusual
-subscriber forms stay syntactic or unresolved when the source does not identify
-a target. Conditional compilation is represented as parsed, not evaluated.
+Object references resolve by object type, ID, name, namespace, app
+preference, and declared dependencies, including symbol packages. Calls are
+exact when the AL compiler is available; without it they resolve by name and
+number of arguments, and dynamic calls and unusual subscriber forms stay
+syntactic or unresolved when the source does not identify a target. Without
+the compiler, conditional compilation is represented as parsed, not
+evaluated.
 
 ## Development
 
@@ -196,7 +250,7 @@ Container:
 
 ```sh
 docker build -t bc-atlas .
-docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/workspace" bc-atlas report /workspace/app --output-dir /workspace/docs/atlas
+docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/workspace" bc-atlas export /workspace/app --view report -o /workspace/docs/atlas
 ```
 
 The AL grammar is pinned in `vendor/tree-sitter-al.wasm`; update it with
@@ -211,8 +265,21 @@ enter that exact version in the workflow form. The workflow rejects mismatched
 or already published versions, runs all checks, and publishes with the selected
 dist-tag. It then tags the commit as `v<version>`, so
 `uses: SchulzOli/BC-Atlas@v<version>` resolves, and creates a GitHub release
-with the version's `CHANGELOG.md` section. It requires an `NPM_TOKEN`
-repository secret.
+with the version's `CHANGELOG.md` section. npm authenticates through
+[trusted publishing](https://docs.npmjs.com/trusted-publishers): the package's
+trusted publisher on npmjs.com is this repository's `publish-npm.yml`
+workflow, so no npm token is stored in GitHub.
+
+
+The VS Code extension in `vscode/` is published by the `Publish VS Code
+extension` workflow: set `version` in `vscode/package.json`, then run the
+workflow with that version. It tests and packages the extension with the
+current engine and publishes it to the Visual Studio Marketplace as the
+publisher `SchulzOli`, signed in with Microsoft Entra ID through GitHub's OIDC
+token (no Marketplace token is stored; see the
+[launch checklist](https://github.com/SchulzOli/BC-Atlas/blob/main/vscode/marketing/README.md#launch-checklist)), and, with
+the secret `OVSX_PAT`, to Open VSX. Every CI run uploads the `.vsix` as the
+`bc-atlas-vsix` artifact.
 
 ## Contributing and support