Prepare bcli for OSS: standard v2.0 examples only, portable custom APIs

AGENTS.md

@@ -36,7 +36,9 @@ you. You do **not** need `--publisher … --group … --version …` — those
 are escape hatches for the rare case where an admin hasn't imported the
 endpoint yet, and they're hidden from `--help` for that reason. If
 `bcli get <name>` errors with `RegistryError`, the fix is to import the
-endpoint into the registry, not to pass override flags.
+endpoint into the registry (`bcli registry import --from-metadata
+--publisher P --group G --version V`, see
+[`docs/custom-apis.md`](docs/custom-apis.md)), not to pass override flags.
 
 ---
 
@@ -47,17 +49,21 @@ redundant flags that the profile + registry already supply.
 
 ```bash
 # ❌ Don't write this:
-bcli -c LLC get fixedAssets --publisher beautech --group finance --version v1.5 --all -f json
+bcli -c CRONUS get fixedAssets --publisher contoso --group finance --version v1.5 --all -f json
 
 # ✅ Write this:
-bcli -c LLC get fixedAssets
+bcli -c CRONUS get fixedAssets
 ```
 
 Why each flag was wrong:
 
-- `--publisher beautech --group finance --version v1.5` — the
-  registry resolves these automatically. Only pass them if the
-  endpoint isn't in the registry (and even then, prefer importing it).
+- `--publisher contoso --group finance --version v1.5` — redundant at
+  best and wrong at worst. `fixedAssets` is a standard v2.0 entity, so
+  these flags point the request at a custom route that doesn't serve
+  it. For custom endpoints already in the registry, the registry
+  resolves publisher / group / version automatically. Only pass them
+  if the endpoint isn't in the registry (and even then, prefer
+  importing it).
 - `--all` — pulls **every** page. Most asks need `--top 5` or no
   pagination flag at all. Use `--all` only when the user explicitly
   asks for a full export.
@@ -76,7 +82,7 @@ when the user's question demands them.
 
 The custom registry an organization installs may be a curated subset of
 BC's catalog. Names are case-sensitive and not always plural-of-the-
-obvious-singular (e.g. `preservationStatuses`, not `preservationStatus`).
+obvious-singular (e.g. `agedAccountsPayables`, not `agedAccountsPayable`).
 The recipe:
 
 ```bash
@@ -99,7 +105,7 @@ markdown / json formats render every column in full.
 ## Field discovery — don't guess fields either
 
 BC custom-API field names sometimes look nothing like the column you'd
-expect (`serialNo` rather than `serialNumber`, `no` rather than
+expect (`vendNo` rather than `vendorNumber`, `no` rather than
 `number`). Don't pass `--filter "<guess> eq 'X'"` and hope for the
 best — that's 1–2 wasted tool calls per guess.
 

CHANGELOG.md

@@ -7,8 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `bcli registry import --from-file` reads a registry file in JSON or YAML, or
+  a Postman collection. A file can set `publisher` / `group` / `version` once
+  at the top and list endpoints by bare entity-set name. See
+  `examples/custom-apis.yaml`.
+- `bcli registry import --from-metadata` takes `--publisher`, `--group` and
+  `--version` directly instead of requiring them in the profile.
+- `bcli registry export` writes a profile's custom endpoints to a portable
+  file for teammates, packs, or team bundles. Pack registry presets accept the
+  same format.
+- Registry entries accept the short keys `publisher` / `group` / `version`
+  alongside `api_publisher` / `api_group` / `api_version`.
+
+### Changed
+
+- `bcli registry import` merges with the existing registry instead of
+  overwriting it, so importing a second API route no longer drops the first
+  and no longer deletes pack-installed endpoints. Pass `--replace` for the old
+  behaviour (pack-installed endpoints are still kept).
+- A registry entry that names only part of a custom route is rejected instead
+  of silently routing to the standard v2.0 API.
+- `--from-postman` and `--from-json` still work but are hidden in favour of
+  `--from-file`.
+
 ### Fixed
 
+- The "endpoint not registered" hint suggested
+  `bcli registry import --from-metadata <metadata-url>`, which is not valid
+  syntax.
+
 - Interactive auth no longer prompts roughly once an hour. `BrowserAuth` and
   `DeviceCodeAuth` both built `msal.PublicClientApplication` without a
   `token_cache=`, so MSAL's cache existed only in memory. In a fresh process —

README.md

@@ -60,8 +60,8 @@ bcli get customers --top 5
 bcli get vendors --filter "displayName eq 'Fabrikam'" --format json
 bcli get salesInvoices --select number,totalAmountIncludingTax --top 10
 
-# Import custom APIs from a Postman collection
-bcli registry import --from-postman ./my_collection.json
+# Register your own AL API pages straight from BC
+bcli registry import --from-metadata --publisher contoso --group integration --version v1.0
 
 # Query custom endpoints (route auto-resolved)
 bcli get myCustomEntities --top 5
@@ -70,7 +70,7 @@ bcli get myCustomEntities --top 5
 ## Features
 
 - **Works out of the box** — 79 standard BC v2.0 entities (customers, vendors, items, GL entries, ...) with zero configuration beyond auth
-- **Custom API support** — Import your custom API pages from Postman collections, JSON, or live `$metadata`
+- **Custom API support** — Register your own AL API pages from live `$metadata`, a short YAML/JSON file, or a Postman collection, and share them with `bcli registry export`
 - **Three-tier endpoint resolution** — Custom registry -> standard v2.0 -> fuzzy suggestions
 - **Multi-company** — Assign aliases to companies and query across all entities
 - **OData query builder** — `--filter`, `--select`, `--expand`, `--orderby`, `--top`, `--skip` on every query