bc-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{bc_cli-0.3.0 → bc_cli-0.4.0}/AGENTS.md

@@ -161,6 +161,106 @@ user, don't loop.
 
 ---
 
+## Mutation result envelope — read this, not stdout
+
+For real writes (not dry-run), pass `--result-out PATH` (or
+`--result-fd N` on Unix harnesses) and parse the JSON envelope written
+there. The envelope is the canonical record of what happened — stdout
+is for human consumers; agents shouldn't scrape it.
+
+```bash
+bcli --profile p post vendors --data '{"...": "..."}' --result-out /tmp/r.json
+# then jq < /tmp/r.json
+```
+
+The envelope is an 18-field JSON object: `invocation_id`,
+`tool_version`, `profile`, `environment`, `company`, `method`,
+`endpoint`, `resolved_url`, `record_id`, `dry_run`, `status`
+(`succeeded` / `failed`), `exit_code`, `bc_correlation_id`,
+`telemetry_event_id`, `audit_log_offset`, `started_at`,
+`duration_ms`, plus `version` of the envelope schema. Atomic write
+(tmp + `os.replace` + `fsync`) — the file appears whole or not at all.
+
+**Failed envelopes** keep the same shape with `status="failed"`,
+`exit_code` per the taxonomy below, and `bc_correlation_id` set when
+BC returned one. Use it to diagnose without scraping a Python
+traceback off stderr.
+
+For `bcli batch run`, the envelope's `record_id` IS the ledger run id.
+Pivot from there to `bcli batch state <run-id>` for per-step detail.
+
+## Batch operation state
+
+`bcli batch run` writes a durable SQLite ledger that survives SIGKILL.
+Three new commands let you inspect and undo runs:
+
+```bash
+bcli batch list --format json                  # recent runs, newest first
+bcli batch state <run-id> --format json        # per-step detail for one run
+bcli batch rollback <run-id> --dry-run         # preview undo
+bcli batch rollback <run-id>                   # apply undo (POST→DELETE only)
+```
+
+`bcli batch list` filters with `--state STATE` (`completed`, `failed`,
+`partially_committed`, `rolled_back`, `running`, `cancelled`). Use
+`partially_committed` to find runs that died mid-way — those are where
+ledger-based recovery is worth the cost.
+
+Rollback issues `DELETE` for committed POSTs only. PATCH and DELETE
+steps are marked `rollback_skipped` because there's no clean inverse
+without a pre-image snapshot. `disable_writes` profiles refuse rollback
+outright (no `--yes` bypass) — that's by design.
+
+## Exit code taxonomy
+
+Don't treat all non-zero as "generic error." The taxonomy is
+documented in `bcli describe`'s `exit_codes` field:
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | generic crash / unhandled exception |
+| 2 | usage error (bad flag, missing arg) |
+| 3 | auth (token expired, login required) |
+| 4 | not found (endpoint, record, profile) |
+| 5 | validation (filter, param schema) |
+| 6 | remote 4xx (BC rejected the request) |
+| 7 | remote 5xx (BC server error) |
+| 8 | policy refusal (`disable_writes` triggered without `--yes`) |
+
+Key off the specific code. Exit `8` means "the profile is read-only";
+prompting for `--yes` and retrying is the right move. Exit `3` means
+"run `bcli auth login --profile X`." Exit `1` is the only one that
+warrants "report to user and stop."
+
+## Idempotency keys for retries
+
+For mutations you might retry, pass `--idempotency-key K`. The IETF
+`Idempotency-Key` HTTP header goes out on the first call so any
+gateway-level dedup applies; subsequent retries within the same `bcli
+batch run` short-circuit through the ledger (no second HTTP, no
+duplicate row).
+
+```bash
+KEY=$(uuidgen)
+bcli post vendors --data '{"...":"..."}' --idempotency-key "$KEY" --result-out r.json
+# If you need to retry, reuse the same KEY — same-run replay is safe.
+```
+
+Inside a batch YAML, declare per-step:
+
+```yaml
+steps:
+  - name: create_vendor
+    action: post
+    endpoint: vendors
+    idempotency_key: "${{ params.vendor_no }}-2026Q2"
+    body: { ... }
+```
+
+Cross-run replay is deferred (would mean scanning every ledger DB); the
+header is sent on every retry so gateway-level dedup remains in play.
+
 ## Dry-run before writes
 
 Before any `post` / `patch` / `delete` / `attach upload`, run with `--dry-run`
@@ -226,15 +326,26 @@ on, and the CLI exit code is the answer when it's off.
 
 If the user has mounted `bcli-mcp` (see [`docs/mcp-server.md`](docs/mcp-server.md)),
 prefer those tools — they collapse discovery + query into single calls
-with structured results:
-
-- `list_endpoints()` — full registry as JSON
-- `describe_endpoint(name, discover_fields=True)` — metadata + field
-  discovery in one call
-- `query(endpoint, filter, ...)` — the same as `bcli get`, but typed
+with structured results. As of 0.4.0 the MCP server generates 23 tools
+dynamically from `bcli describe`, including five new mutating verbs
+(`bcli_post`, `bcli_patch`, `bcli_delete`, `bcli_attach_upload`,
+`bcli_batch_run`) that internally pass `--result-out` and return the
+envelope as the tool result.
+
+**Tool names match the CLI command path** (`bcli_get`,
+`bcli_endpoint_list`, `bcli_endpoint_info`, `bcli_endpoint_fields`,
+`bcli_company_list`, …). The pre-0.4.0 names (`query`,
+`list_endpoints`, `describe_endpoint`, `list_companies`) are gone — see
+the migration table in [`docs/mcp-server.md`](docs/mcp-server.md) if
+your client config references the old names.
+
+For mutating tools, a `status="failed"` envelope surfaces as MCP
+`ToolError` with the BC correlation id quoted in the error message —
+you don't need to read the envelope separately for failures.
 
 The CLI recipes above still work fine if the MCP server isn't
-available; this is purely an "if you've got it, use it" optimization.
+available; the MCP tools are an "if you've got them, use them"
+optimization.
 
 ---
 

{bc_cli-0.3.0 → bc_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,159 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-18 — Agent Interface Profile v0.1
+
+The Agent Interface Profile (AIP) v0.1 lands: a small kernel of CLI
+primitives that any agent runtime can drive deterministically, without
+parallel schemas or hand-written MCP tools.
+
+### Added
+
+- **`bcli describe --format json`** — canonical machine-readable
+  projection of the live Typer surface + endpoint registry + active
+  profile. One command MCP, completions, and docs all consume; new CLI
+  commands light up automatically. Cached at
+  `~/.config/bcli/describe/<profile>.<hash>.json` with mtime
+  invalidation. Subtree mode (`bcli describe get`, `bcli describe batch
+  run`) returns narrow output for token-constrained agents. Includes
+  forward-compat declarations: `emits_result_envelope`,
+  `emits_operation_state`, `requires_confirmation: "production"`, plus
+  the new `exit_codes` taxonomy and per-command `positionals` /
+  `required` / `limits` extensions.
+- **Mutation result envelope (`--result-out PATH` / `--result-fd N`)**
+  on every mutating verb (`post`, `patch`, `delete`, `attach upload`,
+  `batch run`). Frozen 18-field JSON envelope written atomically
+  (`os.replace` + `fsync`); contains profile, environment, company,
+  method, endpoint, resolved URL, record id, status, exit code, BC
+  correlation id, started_at, duration_ms. Failed envelopes carry the
+  exit code (4 = not found, 6 = remote 4xx, 7 = remote 5xx, 8 = policy
+  refusal, etc.) so an agent can read it side-channel and act without
+  scraping stdout. For `batch run` the envelope's `record_id` is the
+  ledger run id — pivot directly to `bcli batch state <run-id>` for
+  per-step detail.
+- **Batch operation ledger (SQLite)** — one
+  `~/.config/bcli/batch/<run-id>.db` per `bcli batch run` invocation.
+  WAL + `synchronous=NORMAL`, intent row written before each HTTP call
+  (survives SIGKILL); outcome row after. Derived run state
+  distinguishes `partially_committed` from a stale `running` stamp. New
+  commands: `bcli batch state <run-id>`, `bcli batch list [--state
+  STATE] [--limit N]`, `bcli batch rollback <run-id> [--dry-run]
+  [--yes]`. Rollback issues `DELETE` for committed POSTs only; PATCH /
+  DELETE marked `rollback_skipped` (no clean inverse without pre-image
+  snapshots). `disable_writes` is a hard refusal on rollback (no
+  `--yes` bypass).
+- **Exit code taxonomy** — `bcli.exit_codes` defines 0/1/2/3/4/5/6/7/8
+  with short labels; `bcli describe` projects the map; centralized
+  error handler maps `BCLIError` subclasses (`AuthError → 3`,
+  `RegistryError → 4`, `ValidationError → 5`, `ConfigError → 2`,
+  `SafetyError → 8`).
+- **"Did you mean" remediation hints** on `BCLIError` paths: auth →
+  `Run 'bcli auth login --profile X'`, config (no profiles) →
+  `Run 'bcli config init'`, config (unknown profile) → fuzzy match,
+  registry (no fuzzy) → `Run 'bcli registry import …'`.
+- **JSON on pipe by default** — when stdout isn't a TTY and no
+  `--format` was passed, emit JSON. Pipelines, redirects, CI steps,
+  agent runtimes all get the canonical machine-readable shape with no
+  flag dance. The `CLAUDECODE` and `BCLI_AGENT` env hints keep their
+  markdown semantics (explicit user opt-in); legacy Windows console
+  host stays on markdown for the mojibake reason. `BCLI_FORMAT` and
+  explicit `--format` always win.
+- **`--idempotency-key KEY`** on `post`, `patch`, `delete`, `attach
+  upload`. IETF `Idempotency-Key` HTTP header sent on the first call
+  (gateway-level dedup remains in play). Same-run replay protection in
+  `bcli batch run`: if two mutating steps share an `idempotency_key:`
+  in the YAML, the second is replayed (no second HTTP, no duplicate
+  ledger row), and the result entry carries `prior_seq`,
+  `prior_step_id`, `prior_bc_correlation_id`. Ledger schema migrates
+  v1 → v2 non-destructively via `ALTER TABLE step ADD COLUMN
+  idempotency_key`.
+- **Progress events (`--progress-fd N`)** on `bcli batch run` and
+  `bcli extract run`. JSON-lines `step_started` / `step_completed`
+  written to a dedicated fd (separate from `--result-fd`). Stderr
+  stays human-readable; the fd channel is structured and stable for
+  agents to demux. Replayed steps emit a synthetic pair with
+  `status="replayed"` so the progress stream tells the truth.
+- **23 dynamically-generated MCP tools** in `bcli_mcp` (was 4
+  hand-written). Server subprocesses `bcli describe` once on startup
+  and registers one tool per command; new CLI commands light up as
+  MCP tools automatically. Five new mutating tools (`bcli_post`,
+  `bcli_patch`, `bcli_delete`, `bcli_attach_upload`, `bcli_batch_run`)
+  pass `--result-out` and return the envelope as their tool result.
+  `status="failed"` envelopes surface as MCP `ToolError` with the BC
+  correlation id quoted.
+- **`AsyncBCClient.delete_url(url, *, etag="*")`** — new SDK method
+  for absolute-URL deletes (used by the rollback path; avoids
+  re-resolving the registry at undo time).
+- **`bcli skill install`** — generates `.claude/commands/bcli-<name>.md`
+  per saved query and per batch template (`~/.config/bcli/batches/
+  <profile>/*.yaml`). Generates a top-level
+  `.claude/skills/bcli/SKILL.md` index grouped by `categories:`.
+  SHA-256 content hash embedded in the provenance comment for
+  byte-stable idempotency — no `generated_at` timestamp, so re-runs on
+  unchanged sources are mtime-preserving no-ops. `manual: true` in a
+  file's YAML frontmatter protects it from regeneration. `--dry-run`
+  previews; `--target` resolves to explicit path > CWD with `.claude/`
+  > `$HOME`. Stdlib only — no jinja2; atomic writes via
+  `tempfile.mkstemp` + `os.replace`.
+- **`bcli skill init`** — interactive wizard that reads `bcli describe
+  --format json` via subprocess, runs 4 Rich prompts (role / top-three
+  daily questions / slash-command style / generate-new-queries y/N),
+  fuzzy-matches existing saved queries against the top-three free
+  text (stdlib `difflib`), and proposes new role-tailored queries via
+  entry-point providers — each with a per-query `[y/N]` approval gate.
+  Generates `~/.claude/skills/bcli-<user>/SKILL.md` with YAML
+  provenance frontmatter. Atomic commit phase: snapshots existing
+  content, writes all targets, restores on first failure. Guardrails
+  via `_assert_writable` restrict writes to `~/.config/bcli/queries/`,
+  `~/.claude/skills/bcli-<user>/`, and `~/.config/bcli/skills/`;
+  symlink-safe via `Path.resolve(strict=False)` + `is_relative_to`.
+- **`bcli skill update`** — idempotent re-run via state cache at
+  `~/.config/bcli/skills/.last-init.json`. The cache persists both
+  the interview answers AND the approved-query bodies so a later
+  `--non-interactive` replay re-writes the same queries verbatim
+  (without re-asking the operator). Describe-payload-hash mismatch
+  refuses silent replay and asks for a re-interview when the describe
+  surface changed under the user's feet.
+- **Saved-query YAML schema extension** — three additive fields
+  (`description`, `categories`, `args`). Existing saved-query bundles
+  without these still work: when `args:` is omitted, `bcli skill
+  install` derives it from `params:` keys (required first, optional
+  second, both in YAML insertion order). Documented in
+  `docs/saved-queries.md`'s new "Slash-command projection" section.
+- **Entry-point group `bcli.skill_init.role_templates`** — OSS bcli
+  ships with an opinion-free default proposer (returns `[]` for every
+  role). Downstream packages plug in role templates by registering
+  callables under this entry-point group via standard Python
+  packaging. Discovered at wizard time via
+  `importlib.metadata.entry_points`. The provider signature is
+  `(interview, payload) -> list[ProposedQuery]`; downstream
+  integrators publish their own integration documentation.
+
+### Changed
+
+- **Policy refusal exit code 1 → 8.** Scripts that grep `if exit==1`
+  for "the read-only profile blocked me" need updating. Agents
+  consuming `bcli describe`'s new `exit_codes` field pick up the new
+  code automatically.
+- **MCP tool renames** (breaking for existing MCP clients — Claude
+  Desktop, MCP Inspector configs referencing the old names need an
+  update):
+  - `query` → `bcli_get`
+  - `list_endpoints` → `bcli_endpoint_list`
+  - `describe_endpoint` → `bcli_endpoint_info` (with
+    `bcli_endpoint_fields` split out for field discovery)
+  - `list_companies` → `bcli_company_list`
+
+  Migration table in `docs/mcp-server.md`. Tool names now consistently
+  match the CLI command path.
+- **MCP `bcli_get --top` cap remains 50 default / 1000 max** — parity
+  with the pre-rewrite hand-written `query` tool. CLI shell users can
+  still pass `--top 100000` directly; the cap is enforced only at the
+  MCP schema level (advisory for agent runtimes).
+- **Stderr routing for `bcli batch run` metadata** — the ledger path
+  and run id print to stderr, not stdout. Stdout matches legacy batch
+  output byte-for-byte (required by the additive constraint).
+
 ### Fixed
 
 - **Clean SIGPIPE handling for piped output** — `bcli <cmd> | head`,
@@ -24,6 +177,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   rows). Affects both `bcli q` saved queries and `bcli batch`
   workflows.
 
+### Breaking changes
+
+The two items above (exit code 1→8 + MCP tool renames) are intentional
+breaking changes called out in the AIP plan. Both have one-line
+migration paths. Skill install / skill init / skill update are
+additive — no breaking changes from the Skills layer.
+
+### Deferred to v0.5
+
+- **Cross-run idempotency replay** — would require scanning every
+  `*.db` in `~/.config/bcli/batch/` on each mutating call. Same-run
+  protection covers the agent-retry case which is the common one;
+  gateway-level Idempotency-Key dedup covers the rest.
+- **`batch run --idempotency-key`** as a run-level flag — collides
+  across multiple mutating steps. Per-step `idempotency_key:` in the
+  batch YAML is the correct surface.
+- **`telemetry_event_id` / `audit_log_offset` on the envelope** —
+  currently always `null`. Wiring requires extending the
+  `TelemetrySink` and audit protocols to return the emitted event id /
+  log offset, touching every backend including the optional Azure
+  Monitor extra.
+- **Plan-token binding for single mutations** — `batch run --plan-out`
+  works; `bcli post --plan-out` does not. Defer until requested.
+- **Direct FastMCP schema-introspection test** — the `__signature__`
+  patch is indirectly covered via tool-list registration tests; a
+  future FastMCP upgrade could silently degrade tool input schemas
+  without breaking tests.
+- **Etag capture in ledger** — rollback DELETEs use `etag="*"`. A
+  future concurrent edit between POST and rollback could clobber.
+- **CWD-relative batch template discovery** for `bcli skill install` —
+  today only `~/.config/bcli/batches/<profile>/*.yaml` is scanned;
+  project-local batches in `./batches/` would also be useful for the
+  per-project `.claude/` workflow.
+- **SKILL.md frontmatter `generated_at` churn cleanup** — the
+  timestamp ticks forward on every `bcli skill update
+  --non-interactive` replay, so the frontmatter changes even when the
+  body is byte-stable. Idempotency tests compare body-only; downstream
+  content-hash watchers would see noise. Cosmetic.
+- **`bcli skill update` separated from `init`** — today
+  `update_command` delegates to `init_command(...)` verbatim.
+  Documented for future evolution.
+- **Public `bcli.skill_init` namespace for the entry-point contract**
+  — downstream packages currently couple to
+  `bcli_cli.commands.skill_init_cmd` for `InterviewState` /
+  `ProposedQuery`. A future release could promote the protocol types
+  to a public `bcli.skill_init` namespace.
+
 ## [0.2.0] — 2026-05-06
 
 ### Added
@@ -249,6 +449,10 @@ moved to `bcli` (April 2026), then to the PyPI distribution name
 `bc-cli` (April 2026, after discovering the `bcli` PyPI name was
 squatted by an unrelated 2018 package).
 
-[Unreleased]: https://github.com/igor-ctrl/bcli/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/igor-ctrl/bcli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/igor-ctrl/bcli/compare/v0.2.0...v0.4.0
+[0.2.0]: https://github.com/igor-ctrl/bcli/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/igor-ctrl/bcli/compare/v0.1.2...v0.1.5
+[0.1.2]: https://github.com/igor-ctrl/bcli/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/igor-ctrl/bcli/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/igor-ctrl/bcli/releases/tag/v0.1.0

{bc_cli-0.3.0 → bc_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bc-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs
 Project-URL: Homepage, https://github.com/igor-ctrl/bcli
 Project-URL: Repository, https://github.com/igor-ctrl/bcli

{bc_cli-0.3.0 → bc_cli-0.4.0}/docs/mcp-server.md

@@ -7,9 +7,17 @@ server that lets MCP-aware clients drive bcli. The intended caller is Claude
 Desktop, but it also works with the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
 and any other client that speaks the spec.
 
-The server is deliberately small (4 read-only tools) and delegates every call
-to the bcli CLI as a subprocess. Profile resolution, auth, retry, telemetry,
-and the read-only `disable_writes` gate are inherited from the CLI for free.
+The server generates its tool list **dynamically** by subprocessing
+`bcli describe --format json` once on startup, and delegates every call to the
+bcli CLI as a subprocess. Profile resolution, auth, retry, telemetry, and the
+read-only `disable_writes` gate are inherited from the CLI for free. New CLI
+commands light up automatically as MCP tools; deprecated ones disappear.
+
+Read commands return parsed stdout JSON. Mutating commands (`bcli_post`,
+`bcli_patch`, `bcli_delete`, `bcli_attach_upload`, `bcli_batch_run`) pass
+`--result-out <tmp>` and return the AIP §Phase 2 result envelope content as
+the tool result. A `status="failed"` envelope surfaces as an MCP `ToolError`
+with the BC correlation id quoted so the agent can cite it.
 
 ## Install
 
@@ -47,8 +55,15 @@ Add a `mcpServers` entry to `~/Library/Application Support/Claude/claude_desktop
 }
 ```
 
-Restart Claude Desktop. You should see four tools register: `query`,
-`list_endpoints`, `describe_endpoint`, `list_companies`.
+Restart Claude Desktop. The server registers one tool per command in
+`bcli describe`'s output — typically ~20 tools, one per read/mutating verb in
+the CLI. Use the MCP Inspector to enumerate them, or run
+`bcli describe --format json` directly to preview what'll appear.
+
+Renames from the pre-Phase-5 surface: the old hand-written `query`,
+`list_endpoints`, `describe_endpoint`, and `list_companies` are now
+`bcli_get`, `bcli_endpoint_list`, `bcli_endpoint_info`, and `bcli_company_list`
+respectively (matching the CLI subcommand paths).
 
 If `bcli-mcp` isn't on Claude Desktop's PATH (uv tool install paths can be
 tricky), use the full path:
@@ -66,17 +81,25 @@ tricky), use the full path:
 
 ## Tool surface
 
+The tool list is generated from `bcli describe --format json` on startup, so
+the canonical reference is the describe output for your install. The most
+useful subset:
+
 | Tool | What it does | Notes |
 |------|--------------|-------|
-| `query` | Run an OData query against an entity. | `top` defaults to 50, capped at 1000. Use `select` to keep payloads small. |
-| `list_endpoints` | List entities the active profile can reach. | Honours `disable_standard_api`, `allowed_categories`, `allowed_endpoints`. |
-| `describe_endpoint` | Show fields, key, supported ops, and route for one entity. | `fields` is populated only after `bcli endpoint fields <name>` has been run. |
-| `list_companies` | Companies on the active environment. | Returns `[{id, name, alias, is_default}]`. |
-
-Mutating commands (`post` / `patch` / `delete`), file uploads, batch runs, and
-admin/setup flows are deliberately not exposed. Claude can always fall back to
-`Bash` + `bcli` directly when those are needed — and that path trips the
-existing `disable_writes` confirmation prompt.
+| `bcli_get` | Run an OData query against an entity. | `top` defaults to 50, capped at 1000 (carried from describe's `limits`). Use `select` to keep payloads small. |
+| `bcli_endpoint_list` | List entities the active profile can reach. | Honours `disable_standard_api`, `allowed_categories`, `allowed_endpoints`. |
+| `bcli_endpoint_info` | Show fields, key, supported ops, and route for one entity. | `fields` is populated only after `bcli endpoint fields <name>` has been run. |
+| `bcli_endpoint_fields` | Discover the fields for one entity and persist them to the local registry. | One BC API call; populates the cache for every future call. |
+| `bcli_company_list` | Companies on the active environment. | Returns `[{id, name, alias, is_default}]`. |
+| `bcli_q` | Run a saved query by name with `${{ params.X }}` substitution. | The "daily questions" surface — hides OData syntax. |
+| `bcli_post` / `bcli_patch` / `bcli_delete` | Mutating verbs. | Server passes `--result-out <tmp>` and returns the AIP §Phase 2 result envelope as the tool result. `status="failed"` raises `ToolError` with the BC correlation id. |
+| `bcli_attach_upload` | Two-phase document attachment upload. | Same envelope contract as the other mutating verbs. |
+| `bcli_batch_run` | Execute a YAML batch file. | Returns an envelope whose `record_id` is the batch ledger run id; pivot to `bcli_describe`'s batch state subcommand for per-step detail. |
+| `bcli_describe` | Re-emit the full describe payload. | The MCP server itself uses this on startup; tools can call it to discover what else is exposed. |
+
+`auth login`, `config init`, and other interactive commands (`effects:
+["other"]` in describe) are filtered out — those are command-line-only.
 
 ## Trust model — why the server resets cwd
 
@@ -95,20 +118,20 @@ sources are then exactly:
 Per-tool calls do not honour a per-request `cwd` argument. The server runs
 with a single fixed working directory for its lifetime.
 
-## BC query objects vs entity pages — what to expect from `query()`
+## BC query objects vs entity pages — what to expect from `bcli_get`
 
 Not every endpoint in BC's OData surface is a fully-featured entity. Some
 are "query objects" — read-only summary pages exposed via OData (e.g.
 `customerSales`, `vendorPurchases`). They behave like entities for `GET`
 but Microsoft's runtime drops `$orderby` and `$filter` support on most of
-them. A `query()` call against one of these with `orderby=` or `filter=`
+them. A `bcli_get` call against one of these with `orderby=` or `filter=`
 will 400 from BC.
 
 How to recognise one: there's no flag in the registry today (it'd require
 a hint per endpoint), so the practical signal is the 400 itself. The
 recovery pattern that works:
 
-1. `query(entity="customerSales", top=1000)` — pull a bounded page.
+1. `bcli_get(endpoint="customerSales", top=1000)` — pull a bounded page.
 2. Sort the result client-side in your reasoning step.
 3. Take the top N.
 
@@ -119,24 +142,22 @@ you may miss the actual top customer. For BC tenants with very large
 summary pages, fall back to `bcli get …` via Bash with `--all` (which
 follows pagination).
 
-Entity pages (most of `bcli endpoint list`) support full OData. Use
-`describe_endpoint(name)` to see whether `fields_discovered` is `true`
+Entity pages (most of `bcli_endpoint_list`) support full OData. Use
+`bcli_endpoint_info(name)` to see whether `fields_discovered` is `true`
 and what `fields` look like; the registry doesn't currently track which
 endpoints are query objects vs entities, so you'll learn this empirically.
 
-## Discovering field names — `discover_fields`
+## Discovering field names
 
-`describe_endpoint(name)` returns `fields: []` and `fields_discovered:
+`bcli_endpoint_info(name)` returns `fields: []` and `fields_discovered:
 false` if the local registry hasn't probed BC for that entity yet. Two
 ways to recover, in order of cost:
 
-1. Cheapest: call `query(entity=name, top=1)` once and read the keys off
-   the returned record. No registry mutation, zero cache pollution.
-2. One-time: pass `discover_fields=true` to `describe_endpoint`. The
-   tool runs `bcli endpoint fields <name>` first, which fetches one
-   record, persists the field names to the local registry, and then
-   returns the populated metadata. Every subsequent call (any user, any
-   session) gets `fields_discovered: true` for free.
+1. Cheapest: call `bcli_get(endpoint=name, top=1)` once and read the keys
+   off the returned record. No registry mutation, zero cache pollution.
+2. One-time: call `bcli_endpoint_fields(name)`. That fetches one record,
+   persists the field names to the local registry, and every subsequent
+   call (any user, any session) gets `fields_discovered: true` for free.
 
 Pick (1) for one-shot analysis. Pick (2) when the entity is one you'll
 revisit a lot — the registry-cached field list also feeds bcli's
@@ -148,9 +169,11 @@ Pairing an MCP server with a CLI tool is empirically token-favorable for
 **bounded, schema-stable** responses. The OSS server ships with two
 guard-rails baked in:
 
-* `query.top` defaults to 50 (max 1000) — an unbounded request can't pull a
-  whole table into context.
-* Tool docstrings are short. The schema-payload Claude sees is small.
+* `bcli_get.top` defaults to 50 (max 1000) — the safety bound is carried from
+  `bcli describe`'s `limits` field, so an unbounded request can't pull a whole
+  table into context.
+* Tool descriptions come straight from the CLI's docstrings. They're short by
+  construction — the schema-payload Claude sees is small.
 
 It is **not** universally a token win. For browse-style "show me everything"
 workflows, falling back to `bcli get <entity> --format markdown` via Bash is

{bc_cli-0.3.0 → bc_cli-0.4.0}/docs/saved-queries.md

@@ -59,7 +59,9 @@ queries:
 
 | Field          | Type     | Notes                                                    |
 |----------------|----------|----------------------------------------------------------|
-| `description`  | string   | Shown in `bcli q` listing.                               |
+| `description`  | string   | Shown in `bcli q` listing **and** the generated slash command's frontmatter. |
+| `categories`   | list[str] | Optional. Used by `bcli skill install` to group commands in the generated `SKILL.md` index. Falls back to `["unsorted"]`. |
+| `args`         | list[obj] | Optional. Explicit positional ordering for the generated slash command. If omitted, inferred from `params:` keys (required first, optional second). See *Slash-command projection* below. |
 | `endpoint`     | string   | Required. Entity-set name (resolved through the registry).|
 | `params`       | mapping  | Optional. Each key declares a parameter; see *Param declarations* below. |
 | `filter`       | string   | OData `$filter`. Supports `${{ params.X }}` substitution. |
@@ -162,3 +164,74 @@ bcli --profile ops q items-low-stock min=10
 * `--format` — override the active profile's output format (`json`,
   `markdown`, `csv`, `ndjson`, `table`).
 * `--dry-run` (global) — skips execution after resolving.
+
+## Slash-command projection (`bcli skill install`)
+
+`bcli skill install` reads the saved queries for the active profile and
+generates one Claude Code slash command per query at
+`<target>/.claude/commands/bcli-<name>.md`, plus a top-level skill index
+at `<target>/.claude/skills/bcli/SKILL.md` grouped by `categories:`.
+
+Three optional fields on each query feed the generator:
+
+```yaml
+queries:
+  utilization-by-esn:
+    description: Engine utilization (cycles, hours, FSN) for an ESN
+    categories: [aviation, daily-ops]
+    args:
+      - name: esn
+        type: string
+        example: "424322"
+        required: true
+    # existing fields below — params/filter/select/etc.
+    endpoint: util_history
+    params:
+      esn: {required: true}
+    filter: "engine_serial eq '${{ params.esn }}'"
+```
+
+* `description` — used as the slash command's frontmatter `description:`
+  and listed under its category in `SKILL.md`.
+* `categories` — list of strings. Each category becomes a section in
+  `SKILL.md`. Queries with no categories land under `unsorted`.
+* `args` — explicit positional ordering for the generated slash command
+  body. Each entry: `{name, type, required, example}`. **If omitted, the
+  generator derives `args:` from `params:` keys** (required first,
+  optional with `default:` second, both in YAML insertion order). For
+  most queries you can leave `args:` out and the projected command will
+  still work; declare it explicitly when you want a different ordering
+  than the params dict gives you.
+
+The generated command body invokes `bcli q <name> arg1=$1 arg2=$2 …
+--format json`, so the positional → key mapping in the slash command
+matches your `args:` order.
+
+### Idempotency and manual overrides
+
+* Each generated file embeds a `content_hash: sha256:…` line in its
+  provenance comment. Re-running `bcli skill install` on unchanged
+  sources is a no-op (hash matches → file isn't rewritten).
+* To protect a hand-edited slash command file from regeneration, add
+  `manual: true` to its YAML frontmatter:
+  ```markdown
+  ---
+  manual: true
+  description: My customised command
+  ---
+  ```
+  The installer skips any file whose frontmatter declares `manual: true`,
+  even if a saved query by the same name exists.
+* Add `--dry-run` to preview without writing; add `--target PATH` to
+  point at a specific project root (defaults to CWD when it contains a
+  `.claude/` directory, else `$HOME`).
+
+### Batch templates
+
+Batch workflow YAMLs under `~/.config/bcli/batches/<profile>/*.yaml` are
+projected the same way as saved queries — one
+`.claude/commands/bcli-batch-<name>.md` per file, body invoking
+`bcli batch run <yaml> --set arg=$1 --format json --result-out …`.
+
+CWD-relative batch discovery (a `batches/` directory checked into a
+project repo) is a follow-up — open an issue if you need it.

{bc_cli-0.3.0 → bc_cli-0.4.0}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "hatchling.build"
 # installed CLI binary (`bcli`) are unaffected — only `pip install` /
 # `uv tool install` use this name.
 name = "bc-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python SDK and CLI for Microsoft Dynamics 365 Business Central APIs"
 readme = "README.md"
 license = "Apache-2.0"

bc_cli-0.4.0/src/bcli/batch/__init__.py

@@ -0,0 +1,9 @@
+"""Batch operation ledger (Phase 3 of AIP v0.1).
+
+A durable SQLite ledger that records every batch run's intent + outcome
+per step.  Survives ``SIGKILL`` because the intent row is written
+*before* the HTTP call, and ``PRAGMA synchronous=NORMAL`` keeps WAL
+honest at commit time.
+"""
+
+from bcli.batch.ledger import Ledger, RunLedgerExistsError  # noqa: F401