Guided setup

bca setup decides once what BC Atlas should do in a repository:

• Features: health check, architecture report, user guides or test cases, object catalog.
• Triggers: Git hooks (Husky or plain Git), pull requests, and a schedule (cron).
• Sync: what happens with generated files. Each trigger can verify, stage, publish, commit, or open a pull request.

Everything ends up in .bca.json, Git hook files, and one pipeline file. All of them call bca run, so local hooks and pipelines behave the same way.

You choose how to answer the questions:

Way	Command	For
Terminal wizard	bca setup	Answering the questions yourself
Recommendations	bca setup --yes	Taking the detected defaults
Your AI agent	bca setup agent --agent claude then /bca-setup	A guided conversation that explains the options
Scripts	bca setup plan + bca setup apply ...	CI templates and repeatable setups

The agent is optional. It never edits files itself; it asks the questions and calls bca setup apply.

What setup detects

bca setup plan ./app

BC Atlas setup for BC Atlas Warehouse Example 1.0.0.0

  Git                yes (github)
  UI tests           2 documented scenario(s) in .
  Translations       de-DE
  Existing setup     none

Recommended answers
  --features         check, report, docs
  --tests            .
  --hooks            husky
  --pre-commit       check
  --pre-push         report, docs
  --hook-sync        verify
  --ci               github
  --ci-sync          verify
  --schedule         0 6 * * 1
  --schedule-sync    pull-request
  ...

--format json returns the same data for tools: detected facts, every question with its flag, options, recommended value, and when condition, and a ready apply command.

Questions

Topic	Flag	Choices
Features	--features	check, report, docs, codegraph
UI tests	--tests	Folder with documented AL UI tests (for docs)
Doc formats	--docs-export	markdown, html, dita, ado-csv, bpmn
Doc type	--docs-as	guide, testcase
Language	--language	e.g. en-US, de-DE (captions from the app's XLIFF)
Git hooks	--hooks	husky, git, none
Editor	--editor	vscode, none (recommended when a .vscode folder exists)
Updates	--updates	dependabot (GitHub, with Husky), none
Before commit	--pre-commit	features, or none; keep it fast
Before push	--pre-push	features, or none
Hook sync	--hook-sync	verify, stage, none
Pipeline	--ci	github, azure-devops, none
Pipeline sync	--ci-sync	verify, artifact, none
Schedule	--schedule	cron expression in UTC, or none
Schedule sync	--schedule-sync	pull-request (GitHub), commit, artifact, verify, none

Omitted answers use the recommendation. Lists are comma-separated, and none means an empty list.

Apply

bca setup apply ./app --features check,report,docs --tests test \
  --hooks husky --pre-commit check --pre-push report,docs --hook-sync verify \
  --ci github --ci-sync verify --schedule "0 6 * * 1" --schedule-sync pull-request \
  --dry-run

--dry-run lists what would be created or updated. Without it, setup writes:

File	When
<app>/.bca.json	Always. Existing settings are kept and the automation and docs sections are updated.
.husky/pre-commit, .husky/pre-push	--hooks husky. Existing hook commands are kept, and the BC Atlas line is added or replaced.
package.json	--hooks husky. Adds husky and bc-atlas as dev dependencies and "prepare": "husky".
.githooks/pre-commit, .githooks/pre-push	--hooks git. Setup also runs git config core.hooksPath .githooks.
.github/workflows/bc-atlas.yml	--ci github
azure-pipelines.bc-atlas.yml	--ci azure-devops
.vscode/tasks.json	--editor vscode. In the app folder when it has .vscode, else in the repository root. Existing tasks are kept; earlier BC Atlas: tasks are replaced. A file with comments is only rewritten with --force.
<app>/.bca/.gitignore	--editor vscode. Keeps local output such as the live diagram out of Git.
.github/dependabot.yml	--updates dependabot. Creates the file, or adds an npm entry for bc-atlas and husky to an existing updates list.

Pipeline files that were not generated by bca setup are never overwritten unless you pass --force. Running apply again with the same answers changes nothing. The result ends with the next steps, for example npm install for Husky and a first bca run.

Local development

Setup covers the whole local loop, not only pipelines:

Moment	What runs	Configured by
While you edit	The recommended BC Atlas extension: the panel, Problems, and CodeLens update on every AL change	--editor vscode (writes .vscode/extensions.json)
On demand	BC Atlas: Health check (findings in the Problems panel with file and line), Architecture report, User documentation	--editor vscode
Before committing	BC Atlas: Run pre-commit hook / Run pre-push hook: the exact hook command, without committing	--editor vscode
git commit	The pre-commit tasks through Husky or .githooks	--hooks, --pre-commit
git push	The pre-push tasks, with verify or stage sync	--hooks, --pre-push, --hook-sync
On a timer	bca run --trigger schedule from cron, when no pipeline is used	--schedule
Changing the setup	BC Atlas: Set up automation opens the wizard in the terminal	--editor vscode

Run the tasks with Terminal > Run Task, or bind them to keys. With Husky, the tasks and the hooks use the same locally installed bca (npx --no-install bca), so they always run the same version.

Staying up to date

With Husky, the BC Atlas version lives in package.json. Git hooks, VS Code tasks, and the generated pipeline (npm ci + npx --no-install bca) all use that one version. Without a package.json, hooks, tasks, and pipelines pin bc-atlas@<version>.

How	What happens
Notice	In a terminal, any bca command prints BC Atlas 0.8.0 is available (you have 0.7.0). Run "bca update" to see what's new. once a newer version exists.
bca update	Shows the release notes, asks "Update to 0.8.0 now?", installs it, and regenerates the setup files with bca setup apply --from-config.
Dependabot (--updates dependabot)	Opens a pull request for each new bc-atlas version. The pipeline in that pull request shows whether everything still works with it.

The notice never appears in CI, Git hooks, bca run, or JSON output. Turn it off with BCA_NO_UPDATE_CHECK=1.

Let your agent guide the setup

bca setup agent --agent claude    # .claude/commands/bca-setup.md   -> /bca-setup in Claude Code
bca setup agent --agent copilot   # .github/prompts/bca-setup.prompt.md -> /bca-setup in VS Code Copilot Chat
bca setup agent --agent cursor    # .cursor/commands/bca-setup.md   -> /bca-setup in Cursor
bca setup agent                   # prints the prompt for any other agent

The command file tells the agent to:

1. Run bca setup plan --format json and summarize what it found.
2. Ask the questions topic by topic, offering the recommendations.
3. Preview the answers with bca setup apply ... --dry-run --format json.
4. Apply after your confirmation and follow the next steps.

Agents connected through MCP can use the same flow with the bc_atlas_setup_plan, bc_atlas_setup_apply (dry run by default), and bc_atlas_run tools; see Agent integration.

To change the setup later, run bca setup or /bca-setup again. The plan starts from your current .bca.json.