Refine Briosa documentation architecture, catalog, and API references

AGENTS.md

@@ -11,21 +11,43 @@ repository settings.
   exact-target MP command catalog. Never make prose, examples, navigation, or
   catalog pages the accidental source of truth for protocol semantics.
 - Product and operation guidance may describe only committed, supported Briosa
-  behavior. The MP command catalog may also document selected, under-review,
-  deferred, intentionally excluded, and SDK-unavailable commands when each
-  entry is clearly labeled and traces to a reviewed disposition.
+  behavior. The MP command catalog may also document next, undecided,
+  uncommitted, excluded, and SDK-unavailable commands when each entry is
+  clearly labeled and traces to a reviewed disposition.
 - A catalog entry does not make a command part of the Briosa API. Only the
-  `supported` catalog status is a runtime-support claim, and it must agree with
+  `current` catalog status is a runtime-support claim, and it must agree with
   authoritative handwritten protobuf, operation registration, and runtime
   capability source in `spatialanalyzer/briosa`.
 - Retained inventories and historical evidence may support documentation
-  review, but their membership never establishes support or v1 selection.
-- Organize catalog content as logical category or workflow pages containing
-  several related MP commands. Do not default to one page per command.
+  review, but their membership never establishes current or next status.
+- Preserve the exact target's SpatialAnalyzer MP group hierarchy as the primary
+  catalog information architecture. For an SDK-observed command, use the
+  reviewed exact-target group path supplied by the maintainers.
+- Keep exact-target group pages as lightweight navigation indexes that link to
+  canonical cross-version command sections. A canonical section records
+  reviewed SA availability, group history, signature revisions, and per-target
+  Briosa status without duplicating the full command prose for every SA release.
+- Preserve one stable canonical anchor per reviewed command lineage. Do not
+  merge renamed or superseded identities into one lineage without maintainer
+  review. When search is introduced, index canonical command sections rather
+  than the exact-target navigation indexes.
+- Never expose private evidence-repository paths or internal evidence filenames
+  in the published site. Preserve the exact MP editor label and punctuation in
+  catalog prose, including labels such as `BSplines` and `API - LADAR`.
+- Use workflow pages only as secondary cross-links. Do not move a command out
+  of its SA group to create a Briosa-specific primary grouping, and do not
+  default to one page per command.
+- Some documentation-only records and installed-document paths use labels that
+  differ from the SDK-observed hierarchy. Preserve the evidence and resolve those
+  placements through reviewed catalog work instead of silently inventing a
+  crosswalk.
 - Keep the catalog content-first while its information architecture matures.
   Do not introduce a separate command-data schema, generated index, or
   catalog-specific validation framework without a focused reviewed issue.
 - Preserve MP terminology where the source contract does.
+- Use title case for page titles, structural headings, navigation labels,
+  footer headings, and table headers. Preserve exact API identifiers and MP
+  Editor labels even when their casing differs from the surrounding site.
 
 ## Intellectual property and positioning
 

README.md

@@ -22,6 +22,35 @@ Build the same static output used by GitHub Pages:
 npm run check
 ```
 
+The site has three documentation collections:
+
+- `docs/` contains product guidance, setup, concepts, deployment, and contributing information
+- `api/grpc/` contains the versionable Briosa server and gRPC reference
+- `api/dotnet/`, `api/python/`, and `api/javascript/` contain independently
+  versionable client-library references
+- `mp-command-catalog/` contains the complete exact-target SpatialAnalyzer MP catalog and support dispositions
+
+Each reference collection has its own Docusaurus plugin instance and sidebar.
+The `/api` route is an unversioned landing page that helps users choose the
+appropriate reference.
+
+## API reference versions
+
+The product guide and MP command catalog are intentionally unversioned. Each
+API reference follows the release history of the product it documents. Cut a
+reference snapshot only when that product release is ready to publish:
+
+```powershell
+npm run docusaurus docs:version:grpc <server-version>
+npm run docusaurus docs:version:dotnet <dotnet-package-version>
+npm run docusaurus docs:version:python <python-package-version>
+npm run docusaurus docs:version:javascript <javascript-package-version>
+```
+
+Until the first snapshot exists, each API route represents the current
+development surface. Docusaurus creates and maintains independent version and
+sidebar snapshots for each plugin instance.
+
 ## Documentation boundary
 
 The [Briosa server repository](https://github.com/spatialanalyzer/briosa) is the

api/dotnet/get-working-directory.md

@@ -0,0 +1,68 @@
+---
+title: GetWorkingDirectoryAsync
+description: Call SpatialAnalyzer's Get Working Directory MP command from the Briosa .NET client.
+---
+
+# GetWorkingDirectoryAsync
+
+Calls SpatialAnalyzer's `Get Working Directory` MP command and returns its
+`Directory` output as a .NET string.
+
+:::note[Client API Under Development]
+
+This page describes the reviewed public API planned for the first supported
+Briosa .NET package release. Pre-release package checkouts may still expose a
+temporary bootstrap interface.
+
+:::
+
+| API Item | Value |
+| --- | --- |
+| MP Command | [Get Working Directory](/mp-command-catalog/commands/file-operations#get-working-directory) |
+| SpatialAnalyzer Group | File Operations |
+| Briosa Status | **Current** |
+| Client | `BriosaClient` |
+| Method | `GetWorkingDirectoryAsync` |
+| MP Inputs | None |
+| Return Value | `Task<string>` |
+
+## Example
+
+```csharp
+using Briosa.Client;
+
+await using var briosa = new BriosaClient();
+await briosa.StartAsync();
+
+string workingDirectory = await briosa.GetWorkingDirectoryAsync();
+```
+
+`StartAsync()` must complete before the command is called. It starts or joins a
+compatible Briosa session and verifies that SpatialAnalyzer is ready for MP
+execution.
+
+## Signature
+
+```csharp
+public Task<string> GetWorkingDirectoryAsync(
+    CancellationToken cancellationToken = default);
+```
+
+The command has no MP inputs. The optional `cancellationToken` controls how long
+the caller waits; it is not part of the MP command.
+
+## Return Value
+
+The task completes with the working directory reported by SpatialAnalyzer. The
+client validates the required MP output and does not expose the generated gRPC
+result envelope.
+
+## Failures and Cancellation
+
+A command failure faults the returned task through the handwritten Briosa
+exception model. Caller cancellation does not prove that an in-flight
+SpatialAnalyzer command was stopped, and the client does not automatically
+replay a call with an uncertain outcome.
+
+- [gRPC operation](/api/grpc/get-working-directory)
+- [Understanding execution outcomes](/docs/concepts/execution-outcomes)

api/dotnet/overview.md

@@ -0,0 +1,22 @@
+---
+title: Briosa for .NET API
+description: Reference documentation for the Briosa .NET client library.
+slug: /
+---
+
+# Briosa for .NET API
+
+This section follows the public API of the Briosa .NET client library. Use it
+to look up client lifecycle, operation methods, result types, exceptions,
+timeouts, and cancellation behavior from C# and other .NET languages.
+
+The first versioned reference will be published with the first supported client
+package release. Until then, these pages describe the reviewed public contract
+being implemented. Pre-release package checkouts may still expose temporary
+bootstrap interfaces.
+
+For task-oriented examples, start with
+[Run your first MP command](/docs/getting-started/first-request). For the
+underlying service contract, use the [gRPC API Reference](/api/grpc).
+
+[View the .NET client repository](https://github.com/spatialanalyzer/briosa-dotnet)

docs/operations/get-i-th-collection-name.md → api/grpc/get-ith-collection-name.md

@@ -1,17 +1,17 @@
 ---
-title: GetIThCollectionName
+title: GetIthCollectionName
 ---
 
-# GetIThCollectionName
+# GetIthCollectionName
 
 Implements the `Get i-th Collection Name` MP for exact target
 `2026.1.0529.7`.
 
-| Contract item | Value |
+| Contract Item | Value |
 | --- | --- |
 | Service | `briosa.AnalysisOperations` |
-| RPC | `GetIThCollectionName` |
-| Operation ID | `analysis_operations.get_i_th_collection_name` |
+| RPC | `GetIthCollectionName` |
+| Operation ID | `analysis_operations.get_ith_collection_name` |
 | Request | optional-presence `int32 collection_index` |
 | Result | optional string `resultant_name` plus shared `execution` details |
 | Classification | read only · global-state read · replay safe |
@@ -21,7 +21,7 @@ while omission fails with `InvalidArgument`. Briosa does not invent an upper
 bound; SpatialAnalyzer reports an out-of-range value through the MP outcome.
 
 ```powershell
-grpcurl -plaintext -d '{"collectionIndex":0}' 127.0.0.1:50051 briosa.AnalysisOperations/GetIThCollectionName
+grpcurl -plaintext -d '{"collectionIndex":0}' 127.0.0.1:50051 briosa.AnalysisOperations/GetIthCollectionName
 ```
 
 The returned name is application data and is not logged by default. After MP

docs/operations/get-number-of-collections.md → api/grpc/get-number-of-collections.md

@@ -7,7 +7,7 @@ title: GetNumberOfCollections
 Implements the `Get Number of Collections` MP for exact target
 `2026.1.0529.7`.
 
-| Contract item | Value |
+| Contract Item | Value |
 | --- | --- |
 | Service | `briosa.AnalysisOperations` |
 | RPC | `GetNumberOfCollections` |

docs/operations/get-working-directory.md → api/grpc/get-working-directory.md

@@ -6,8 +6,11 @@ title: GetWorkingDirectory
 
 Implements the `Get Working Directory` MP for exact target `2026.1.0529.7`.
 
-| Contract item | Value |
+| Contract Item | Value |
 | --- | --- |
+| MP Command | [Get Working Directory](/mp-command-catalog/commands/file-operations#get-working-directory) |
+| SpatialAnalyzer Group | File Operations |
+| Briosa Status | **Current** |
 | Service | `briosa.FileOperations` |
 | RPC | `GetWorkingDirectory` |
 | Operation ID | `file_operations.get_working_directory` |
@@ -28,3 +31,9 @@ prevents the getter from running; getter failure returns a data-loss outcome
 instead of an empty directory.
 
 [View the authoritative operation source](https://github.com/spatialanalyzer/briosa/blob/main/targets/2026.1.0529.7/docs/operations/get-working-directory.md).
+
+## Client Library References
+
+- [.NET `GetWorkingDirectoryAsync`](/api/dotnet/get-working-directory)
+- [Python `get_working_directory`](/api/python/get-working-directory)
+- [JavaScript and TypeScript `getWorkingDirectory`](/api/javascript/get-working-directory)

docs/operations/overview.md → api/grpc/overview.md

@@ -1,24 +1,33 @@
 ---
-title: Supported operations
+title: Briosa gRPC API
+slug: /
 ---
 
-# Supported operations
+# Briosa gRPC API
+
+This reference documents the public gRPC services and MP operations exposed by
+the Briosa server. Use the [.NET](/api/dotnet),
+[Python](/api/python), or
+[JavaScript/TypeScript](/api/javascript) reference when working
+through a first-party client library.
+
+## Supported Operations
 
 The current exact target exposes six handwritten read-only MP operations.
 Each is classified as a global-state read and safe to replay, but runtime policy
 may still deny it.
 
-| Operation ID | gRPC method | Result |
+| Operation ID | gRPC Method | Result |
 | --- | --- | --- |
 | `file_operations.get_working_directory` | `briosa.FileOperations/GetWorkingDirectory` | current working directory |
 | `analysis_operations.get_number_of_collections` | `briosa.AnalysisOperations/GetNumberOfCollections` | collection count |
-| `analysis_operations.get_i_th_collection_name` | `briosa.AnalysisOperations/GetIThCollectionName` | collection name |
+| `analysis_operations.get_ith_collection_name` | `briosa.AnalysisOperations/GetIthCollectionName` | collection name |
 | `construction_operations.get_active_collection_name` | `briosa.ConstructionOperations/GetActiveCollectionName` | active collection name |
 | `utility_operations.get_active_units` | `briosa.UtilityOperations/GetActiveUnits` | active length, angular, and temperature units |
 | `utility_operations.get_working_frame_properties` | `briosa.UtilityOperations/GetWorkingFrameProperties` | working-frame context |
 
 Browse these commands by workflow in the
-[MP command catalog](../mp-command-catalog/overview.md).
+[MP Command Catalog](/mp-command-catalog).
 
 `DiscoveryService/ListCapabilities` returns the intersection of handwritten
 operations, the current isolation mode, and runtime allow/deny policy. It is

api/javascript/get-working-directory.md

@@ -0,0 +1,72 @@
+---
+title: getWorkingDirectory
+description: Call SpatialAnalyzer's Get Working Directory MP command from the Briosa JavaScript and TypeScript client.
+---
+
+# getWorkingDirectory
+
+Calls SpatialAnalyzer's `Get Working Directory` MP command and returns its
+`Directory` output as a JavaScript string.
+
+:::note[Client API Under Development]
+
+This page describes the reviewed public API planned for the first supported
+Briosa JavaScript package release. Pre-release package checkouts may still
+expose a temporary bootstrap interface.
+
+:::
+
+| API Item | Value |
+| --- | --- |
+| MP Command | [Get Working Directory](/mp-command-catalog/commands/file-operations#get-working-directory) |
+| SpatialAnalyzer Group | File Operations |
+| Briosa Status | **Current** |
+| Package Export | `getWorkingDirectory` |
+| MP Inputs | None |
+| Return Value | `Promise<string>` |
+
+## Example
+
+```ts
+import {
+  createBriosaClient,
+  getWorkingDirectory,
+} from '@spatialanalyzer/briosa';
+
+await using briosa = createBriosaClient();
+await briosa.start();
+
+const workingDirectory = await getWorkingDirectory(briosa);
+```
+
+`start()` must complete before the command is called. It starts or joins a
+compatible Briosa session and verifies that SpatialAnalyzer is ready for MP
+execution.
+
+## Signature
+
+```ts
+function getWorkingDirectory(
+  client: BriosaClient,
+  options?: BriosaCallOptions,
+): Promise<string>;
+```
+
+The command has no MP input object. The optional call options contain only an
+`AbortSignal`; they remain separate from the MP command.
+
+## Return Value
+
+The promise resolves to the working directory reported by SpatialAnalyzer. The
+client validates the required MP output and does not expose the generated gRPC
+result message.
+
+## Failures and Cancellation
+
+A command failure rejects the returned promise through the handwritten Briosa
+error hierarchy. Aborting the call does not prove that an in-flight
+SpatialAnalyzer command was stopped, and the client does not automatically
+replay a call with an uncertain outcome.
+
+- [gRPC operation](/api/grpc/get-working-directory)
+- [Understanding execution outcomes](/docs/concepts/execution-outcomes)

api/javascript/overview.md

@@ -0,0 +1,22 @@
+---
+title: Briosa for JavaScript and TypeScript API
+description: Reference documentation for the Briosa JavaScript and TypeScript client library.
+slug: /
+---
+
+# Briosa for JavaScript and TypeScript API
+
+This section follows the public API of the Briosa JavaScript and TypeScript
+client library. Use it to look up client lifecycle, operation methods, result
+types, errors, timeouts, and cancellation behavior for Node.js applications.
+
+The first versioned reference will be published with the first supported client
+package release. Until then, these pages describe the reviewed public contract
+being implemented. Pre-release package checkouts may still expose temporary
+bootstrap interfaces.
+
+For task-oriented examples, start with
+[Run your first MP command](/docs/getting-started/first-request). For the
+underlying service contract, use the [gRPC API Reference](/api/grpc).
+
+[View the JavaScript client repository](https://github.com/spatialanalyzer/briosa-js)