@knowttl/artium-axi 0.0.5 → 0.0.7

package/README.md

@@ -14,8 +14,8 @@ Administrators manage accounts, roles, encrypted service credentials and audit r
 The client follows AXI (Agent eXperience Interface) conventions for discovery, help and structured errors.
 
 **Status: under construction.**
-Falcon, Vectra, Azure, Graph and LDAP are wired into the production server entry point.
-See the [evidence ledger](docs/evidence-ledger.md) for the acceptance boundaries.
+Falcon, Vectra, Azure, Graph, LDAP, Azure DevOps and AWX are wired into the production server entry point.
+See the [evidence ledger](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/evidence-ledger.md) for the acceptance boundaries.
 
 ## Agent Ergonomics
 
@@ -96,7 +96,7 @@ artium-axi setup --host claude --hook
 ```
 
 Use `--host codex`, `--host opencode` or `--host pi` without `--hook` for those hosts.
-See [host paths and configuration overrides](docs/verification-s45.md) for installation locations.
+See [host paths and configuration overrides](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s45.md) for installation locations.
 Setup requires the configured server URL and an authenticated account.
 It fetches reviewed adaptations of the server's pinned upstream skills; command examples run through `artium-axi <tool>` using Artium-managed credentials.
 Skills include granted tools that are disabled; running those tools still returns `TOOL_DISABLED`.
@@ -111,7 +111,7 @@ Artium-managed skills for tools no longer granted are retained and reported, not
 Unmanaged standalone skills outside the current grants are left untouched and unreported.
 Output lists one installed, unchanged or retained row per skill.
 Keep the bundle at its installed path; rerun setup if it moves so recorded invocations are repaired.
-See [host verification](docs/verification-s45.md) for recorded discovery checks and outstanding acceptance.
+See [host verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s45.md) for recorded discovery checks and outstanding acceptance.
 
 ## Other ways to install
 
@@ -209,6 +209,8 @@ The [credential standard](docs/credential-standard.md#9-hosted-contract-artium-a
 | Azure (`az-axi`) | Entra tenant ID, application client ID, client secret or certificate private key and SHA-256 thumbprint, subscription IDs and optional workspace mapping. | `account list`; data-plane roles need their own permitted reads. |
 | Microsoft Graph (`mg-axi`) | Entra tenant ID, application client ID, client secret or certificate private key and SHA-256 thumbprint, administrator-consented Graph application permissions. | `entra user list --limit 1`; other domains need their own permissions. |
 | LDAP (`ldap-axi`) | Verified LDAPS or StartTLS URL, read-only bind identity and password, optional search base and private CA PEM. | `auth status`; binds once and reports the selected identity. |
+| Azure DevOps (`ado-axi`) | Organization, optional default project and either a PAT or tenant ID, client ID and client secret. | `project list --limit 1`. |
+| AWX (`awx-axi`) | Controller HTTPS origin and an existing personal access token. | `job list --limit 1`; job read permissions are required. |
 
 #### Falcon
 
@@ -216,22 +218,25 @@ In the Falcon console, open **Support and resources > API clients and keys** and
 Copy its client ID and secret and record its cloud region: `us-1`, `us-2`, `eu-1` or `us-gov-1`.
 At `/admin/tools/falcon-axi`, enter `clientId`, `clientSecret` and `region`, with `memberCid` only when targeting a Flight Control member tenant.
 Grant `Alerts:read` for detection reads, including the first-call example.
-Grant additional scopes only for the domains you use, following the pinned [API client permission matrix](https://github.com/knowttl/falcon-axi/blob/v0.3.0/README.md#api-client-permissions) and its offline `scopes` command.
+Grant additional scopes only for the domains you use, following the pinned [API client permission matrix](https://github.com/knowttl/falcon-axi/blob/v0.5.0/README.md#api-client-permissions) and its offline `scopes` command.
 For example, account reads need `Assets:read`, while CVE reads need `Vulnerabilities (Falcon Intelligence):read`, distinct from Spotlight vulnerability access.
 NG-SIEM search requires `NGSIEM:write`; Identity Protection directory/timeline queries require `Identity Protection GraphQL:write` plus the documented read scopes, even though those queries read data.
 These are optional domain requirements and do not justify granting other write or response scopes.
+The pinned tool does not change hosts, detections, policies or identities and exposes no arbitrary REST or GraphQL requests.
+Starting and stopping NG-SIEM search jobs are its only tenant-side effects; these investigation operations remain available regardless of the saved write switch.
 Falcon's fixed `auth status` test reports local credential resolution, so also run `artium-axi falcon-axi detection list --limit 1` after enabling and granting the tool.
 
 #### Vectra
 
-Obtain the deployment's canonical HTTPS origin, without a path or trailing slash.
+Obtain the deployment's HTTPS origin; see [credential editor guidance](#browser-administration) for accepted input.
 For QUX, select `kind=qux`, `apiVersion=2.5` and either `auth=token` with `token`, or `auth=oauth` with `clientId` and `clientSecret`.
 QUX OAuth requires appliance release 9.1 or later; `applianceRelease` is optional release metadata.
 For RUX, select `kind=rux`, `apiVersion=3.4`, `auth=oauth`, `clientId` and `clientSecret`; leave `applianceRelease` blank.
 Create a QUX personal token under **My Profile** using a local account, or have a Vectra administrator create an OAuth API client under **Manage > API Clients** and record the displayed ID and secret.
 Tokens inherit their user's rights and clients inherit their assigned role; grant read access to health and the Hosts, Accounts, Detections or other areas you need.
-See [Vectra's credential issuance guidance](https://github.com/vectranetworks/vectraautomatedresponse#getting-a-vectra-api-token-for-vectra-detect-api-v2) and the pinned [Vectra configuration contract](https://github.com/knowttl/vectra-axi/tree/v0.1.5#configuration) for deployment-specific requirements.
-If the deployment uses a private CA, paste its PEM contents into `caBundle`; enter no server file path.
+See [Vectra's credential issuance guidance](https://github.com/vectranetworks/vectraautomatedresponse#getting-a-vectra-api-token-for-vectra-detect-api-v2) and the pinned [Vectra configuration contract](https://github.com/knowttl/vectra-axi/tree/v0.1.7#configuration) for deployment-specific requirements.
+For a credential-specific private CA, paste its PEM contents into `caBundle`; enter no server file path.
+For shared trust across tools, follow the [private CA runbook](docs/runbook.md#tls-inspection-and-private-upstream-cas).
 Keep Native settings empty for read-only use; optional writes need the native operation allowlist and upstream permissions.
 Save, run **Test credential**, enable and grant the tool, then run `artium-axi vectra-axi detection list --limit 1` to check the intended read domain.
 
@@ -316,7 +321,7 @@ Delegated permissions and interactive `User.Read` consent do not authorize this
 | Identity providers | `IdentityProvider.Read.All` |
 | Lifecycle workflows | `LifecycleWorkflows.Read.All` |
 
-For other domains, use the pinned [Graph access and licence guidance](https://github.com/knowttl/mg-axi/blob/v0.1.7/docs/graph-coverage.md) and the command's permission requirements rather than granting every permission.
+For other domains, use the pinned [Graph access and licence guidance](https://github.com/knowttl/mg-axi/blob/v0.1.10/docs/graph-coverage.md) and the command's permission requirements rather than granting every permission.
 Licences still apply: PIM and risk/governance features can fail despite consent, and some commands support only delegated identities.
 Do not add `User.Export.All` just to make a read-only setup pass; data-policy export is a write-class permission.
 
@@ -325,7 +330,7 @@ For a certificate, choose `auth=certificate`, enter the PEM in `privateKey` and
 Leave `allowDeviceCode`, `preview`, `sensitiveAreas` and `writes` at their defaults for the initial read-only setup.
 Save, run **Test credential**, follow the [activation requirements](#browser-administration), enable and grant the tool, then run `artium-axi mg-axi entra user list --limit 1`.
 Hosted application mode acquires tokens silently; do not run upstream `auth login` or supply `--scopes` through Artium.
-See the [evidence ledger](docs/evidence-ledger.md) for recorded local and captain live acceptance; credential setup instructions do not establish acceptance for a new host or every upstream operation.
+See the [evidence ledger](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/evidence-ledger.md) for recorded local and owner live acceptance; credential setup instructions do not establish acceptance for a new host or every upstream operation.
 
 #### LDAP
 
@@ -340,7 +345,8 @@ At `/admin/tools/ldap-axi`, enter `url`, choose `auth=simple`, and enter `bindDn
 Use `ldaps://<directory-host>:636` with `startTls` left at the default (unset) or explicitly `false`, or `ldap://<directory-host>:389` with `startTls=true`.
 Saving an `ldaps://` URL with `startTls=true` is rejected with `INVALID_INPUT` and the message `startTls must be false for this URL.`
 Plaintext simple bind, anonymous authentication, disabled certificate verification and caller-supplied connection or credential overrides are refused.
-If a private CA is required, supply its PEM contents in `caFile`, not a server file path.
+For a credential-specific private CA, supply its PEM contents in `caFile`, not a server file path.
+For shared trust across tools, follow the [private CA runbook](docs/runbook.md#tls-inspection-and-private-upstream-cas).
 The multi-line `caFile` editor preserves newlines through saving and private CA file materialization for each call.
 Artium's CLI has no credential-save command.
 Optional `base` limits the search context; otherwise the pinned tool discovers the directory's default naming context.
@@ -350,9 +356,60 @@ Enter the password itself in the form, never a SecretRef or password-file path.
 Save, run **Test credential**, enable the tool, grant it to a role, then run `artium-axi ldap-axi user list --limit 1` to check directory read permissions.
 **Test credential** runs `auth status`, which performs one bind; failed credentials can count toward directory account lockout limits.
 LDAP is read-only by design and has no editable native write settings.
+LDAP 0.2.0 adds `computer list`, `computer show <identifier-or-dn>` and `server` reads through the same managed identity.
+Computer reads use AD machine accounts or the upstream's stated LDAPv3 device fallback; `server` reports advertised rootDSE capabilities and limits.
 The [LDAP inventory](tools/inventories/ldap-axi.json) owns the supported commands, blocked overrides and resource requirements.
 Local fake-directory and offline profile checks do not establish live directory acceptance.
 
+#### Azure DevOps
+
+Artium uses the [pinned](tools/package.json) `@jeffreyhaen/ado-axi` release without upstream modifications.
+At `/admin/tools/ado-axi`, enter `org`, optional `project`, choose `auth=pat`, and paste the PAT itself into `token`.
+Organization-root URLs such as `https://dev.azure.com/<org>` and `https://<org>.visualstudio.com` normalize to the organization name.
+Artium encrypts the PAT in its credential store and injects it through a private per-call profile and environment variable.
+Do not enter a SecretRef or environment-variable name.
+Create a dedicated PAT scoped to the organization with Work Items, Code and Build read permissions as needed for the commands you use.
+Grant corresponding read-write permissions only for intended mutations; a write switch never grants Azure DevOps permissions.
+For service principal authentication, choose `auth=client-secret` and enter `tenantId`, `clientId` and `clientSecret` instead of `token`.
+Add the service principal as a user in the Azure DevOps organization, in the organization's Entra tenant, and grant the required project permissions before testing.
+Artium acquires and caches an Azure DevOps access token with client credentials and supplies it through a restricted per-call `az` stand-in.
+The stand-in answers only the pinned tool's Azure DevOps token request; no Azure CLI sign-in or device flow is used.
+Save, run **Test credential**, enable the tool, grant it to a role, then run `artium-axi ado-axi project list --limit 1`.
+
+Writes are off by default; follow [write-access administration](docs/runbook.md#roles-credentials-and-health) to enable them.
+Artium classifies every command using the reviewed [ADO inventory](tools/inventories/ado-axi.json), which binds the routing review to upstream source digests.
+Artium manages `--org`, `--profile` and `--config`; those overrides and the top-level `config` and `update` commands are refused.
+Use `--project` to select another project within the managed organization.
+The `api` command accepts relative paths and GET only, even when writes are enabled; body flags and absolute URLs are refused.
+All commands refuse repeated flags, stdin and files.
+Use `pipeline watch --timeout 50` or less to stay within the runner's call timeout.
+Writes are journaled by Artium only; see [audit action classification](#audit-screen-and-api).
+For an interrupted write, run the returned read-back command and follow its inspection guidance before retrying.
+Local fake-service checks do not establish live organization acceptance.
+
+#### AWX
+
+Artium bundles the [pinned](tools/package.json) `awx-axi` package without upstream modifications.
+At `/admin/tools/awx-axi`, enter the controller HTTPS `origin` and paste an existing personal access token into `token`.
+Enter the token itself, never a SecretRef, environment-variable name, password or file path.
+Artium encrypts the token and injects a SecretRef through its private per-call profile; it does not mint or revoke AWX tokens.
+Save, run **Test credential**, enable the tool and grant it to a role, then run `artium-axi awx-axi job list --limit 1`.
+**Test credential** reads one job using the managed token and reports structured authentication, network and TLS diagnostics.
+For a private certificate, inspect and trust it through the tool page; trust is scoped to the saved credential and host.
+HTTP and TLS-verification bypasses are refused.
+
+Writes are off by default.
+The native setting `{"allowWrites": true}` permits only operational writes, which still require upstream `--confirm`: launching, canceling or relaunching runs, approving or denying workflow approvals, project and inventory-source syncs, and notification-template tests.
+Configuration writes, deletes and security writes are always blocked, including resource creation and editing, associations, role grants and token operations.
+Artium never enables AWX's separate configuration, deletion or security write gates.
+Token permissions remain an additional AWX-side limit; the write switch does not grant AWX permissions.
+The generated [AWX inventory](tools/inventories/awx-axi.json) classifies every command and records the reviewed upstream source digests.
+Artium manages origin, TLS and credential selectors, and refuses standalone auth login/logout, setup, config, profile and update commands.
+Stdin, file uploads, server file paths and `@file` values are unsupported; use inline non-secret launch parameters.
+Use `job watch --timeout 50` or less to stay within the runner timeout.
+For an interrupted write, inspect current state using the returned read-back guidance before retrying.
+Local fake-service checks do not establish live controller acceptance.
+
 ### Build from source
 
 The source toolchain requires Node **24.11 or later** and **pnpm 10.22.0**.
@@ -370,7 +427,8 @@ After signing in, run `node dist/cli/artium-axi.mjs setup --host codex` to insta
 The root package remains private for server development; `pnpm build:npm` stages the separate public client package in `dist/npm` using the root package version.
 Run `npm pack --dry-run ./dist/npm` to inspect the client tarball before release.
 Only the bundled CLI, skill, README, LICENSE, NOTICE and client package metadata are included.
-See [npm client releases](docs/runbook.md#npm-client-releases) for automated publishing and owner setup.
+Release automation also publishes the pinned server image to `ghcr.io/knowttl/artium-axi:<release-tag>` with OCI labels and provenance.
+See [release publishing](docs/runbook.md#npm-client-releases) for owner setup and image digest and attestation verification before deployment.
 
 ## Usage
 
@@ -386,7 +444,7 @@ See [npm client releases](docs/runbook.md#npm-client-releases) for automated pub
 | `artium-axi whoami` | Show identity, roles, access expiry and server URL. |
 | `artium-axi tools` | List enabled runtime tools granted through your roles. |
 | `artium-axi tools show falcon-axi` | Show cached status, vetted pinned help and a first-call example. |
-| `artium-axi doctor` | Check server address, certificate, token, CLI version and cached tool health. |
+| `artium-axi doctor` | Check server address, certificate, token, CLI version and cached tool health, with a five-second deadline per request. Stop dependent probes after address or TLS connection failure. |
 | `artium-axi logout` | Remove local tokens and attempt server-session revocation. |
 | `artium-axi setup --host claude --hook` | Install your granted skills and optional Claude Code hook after sign-in. |
 | `artium-axi falcon-axi detection list` | Run a Falcon read through the managed adapter. |
@@ -395,6 +453,9 @@ See [npm client releases](docs/runbook.md#npm-client-releases) for automated pub
 | `artium-axi ldap-axi user list --limit 1` | Run a bounded directory read through the managed adapter. |
 
 Add `--help` to a local command to inspect its accepted flags.
+Top-level help lists command purposes.
+Unknown or unexpected local commands, arguments and flags are rejected before configuration, private-channel reads or network access, with valid choices for the relevant command.
+Rejected tokens are named, except for `login` and `passwd` input, which is identified by position without printing its value because it may contain a password.
 Tool help has two boundaries:
 
 ```sh
@@ -404,7 +465,8 @@ artium-axi falcon-axi --help
 
 The first prints local Artium help without signing in or contacting the server.
 The second forwards `--help` through the authenticated upstream adapter.
-A bare Falcon or Vectra invocation shows upstream help; `artium-axi az-axi` and `artium-axi az-axi home` run the Azure dashboard with ARM authentication.
+A bare `artium-axi falcon-axi` reads recent detections; use `artium-axi falcon-axi --help` for its command list.
+A bare Vectra invocation shows upstream help; `artium-axi az-axi` and `artium-axi az-axi home` run the Azure dashboard with ARM authentication.
 A bare `artium-axi ldap-axi` shows directory discovery with managed-credential guidance.
 Arguments after a tool name belong to upstream, subject to adapter restrictions on credential, configuration and file paths.
 Unknown Azure flags return `INVALID_INPUT` with the flag name, valid flags and a hosted help command.
@@ -431,7 +493,7 @@ Details read bundled manifests and stored health without fetching credentials or
 Discovery and administration show the server's bundled tool versions, as defined by the [API contract](src/shared/api.ts).
 
 Upstream calls preserve stdout, stderr and nonzero exit codes.
-For Falcon, Vectra, Azure, Graph and LDAP, recognized TOON or JSON root `help` suggestions, plain upstream help and bundled tool-detail help use `artium-axi <tool>` commands, including examples originally invoking `npx -y @knowttl/<tool>`.
+For Falcon, Vectra, Azure, Graph, LDAP, Azure DevOps and AWX, recognized TOON or JSON root `help` suggestions, plain upstream help and bundled tool-detail help use `artium-axi <tool>` commands, including examples originally invoking `npx -y @knowttl/<tool>`.
 Recognized flag listings and command suggestions omit managed flags declared in each pinned [tool inventory](tools/inventories/)'s `unsafeOverrides`, including Graph profile, config and scopes selectors.
 LDAP home output lists hosted commands, and recognized connection and TLS recovery hints direct callers to an administrator to update the [stored LDAP credentials](#ldap).
 Unrelated content, literal argument values, unknown formats and truncated streams remain unchanged.
@@ -485,6 +547,10 @@ The last enabled administrator cannot be disabled, demoted or archived.
 Profile, role and archive changes use revision checks; reload stale forms rather than overwriting newer changes.
 Session revocation and administration changes commit with their audit records.
 After 15 minutes without identity confirmation, administration mutations require reauthentication.
+After a tool credential test fails TLS verification, an administrator can inspect its saved endpoint’s certificate and trust it for that credential in one confirmation.
+The UI shows full fingerprints, warnings, expiry and removable trust; hostname and validity verification remain enabled.
+A missing intermediate is fetched automatically only when its chain reaches an already-trusted root.
+See [credential certificate trust](docs/runbook.md#trusting-one-tool-from-the-administration-ui) for inspection, rotation and the network-path warning.
 Administration and account screens share a navigation menu.
 Signed-in screens have a header showing identity, sign-in source and sign-out.
 On administration screens, the header also shows the remaining confirmation window.
@@ -514,21 +580,29 @@ Archived users cannot be enabled through the UI or API; use Disable for temporar
 Credential editors pre-fill non-secret values and never return stored secrets.
 Vectra and Graph use schema-generated fields and validation from their published [AXI credential standard](docs/credential-standard.md) profile schemas.
 Enter secret values themselves, not SecretRefs; leave unused fields blank and enter object fields as advanced JSON and string lists one value per line.
-For Vectra, `origin` must be a canonical HTTPS origin, without a path, credentials or an explicit default port.
-Enter PEM contents in `caBundle`, not a server file path; Artium writes a private CA file for each call.
+Profile-backed credential saves normalize safe differences only when the schema rejects the original value; already valid values, including secrets, remain byte for byte unchanged.
+Rejected strings can have surrounding whitespace removed, including nested object and list values; secret interior whitespace is preserved.
+For Vectra, `origin` accepts surrounding whitespace, a trailing slash, uppercase scheme or host and an explicit default port, saving a canonical HTTPS origin.
+Paths, queries, fragments, embedded credentials and HTTP origins remain invalid.
+Rejected profile input returns `INVALID_INPUT` with field names and failing schema constraints, including string lengths, array bounds, uniqueness and unsupported fields, without echoing submitted values.
+When the authentication branch is identifiable, guidance reports its failures and conflicting field names without instructions from other branches; independent errors are reported together.
+Ambiguous alternatives receive field-combination guidance.
+See [Vectra credential setup](#vectra) for private CA input and shared trust.
 The form exposes the schema's full requirements, including conditional requirements for the chosen authentication kind.
 Azure uses guided source-identity fields because the host brokers resource tokens separately.
 Azure and Graph certificate editors accept one PEM file containing one certificate and its matching unencrypted private key and calculate the fingerprint automatically.
 See the [hosted contract](docs/credential-standard.md#9-hosted-contract-artium-axi) for profile injection.
-Falcon has guided fields even when its pinned package has no credential schema; its injection path stays unchanged.
+Falcon has guided fields; see its [current credential handling](docs/credential-standard.md#per-tool-host-facing-schemas).
 Browser saves keep native settings and retain blank stored secrets for the same identity.
-Changing mode, kind, authentication, tenant, client or origin requires new secrets.
+Identity changes require new secrets as defined by the [credential-save contract](src/shared/api.ts) (`adminToolRoutes.save`).
 Select **Test after saving** to save and report a harmless credential check inline.
+After saving, the page reports applied normalizations and reloads stored non-secret values; secret notices name only the field and change, never the value.
 See the [credential-save contract](src/shared/api.ts) (`adminToolRoutes.save`) for API inputs and complete replacement semantics.
 See [credential rotation](docs/runbook.md#roles-credentials-and-health).
 Native settings also replace the entire object; `{}` clears it.
 Credential changes clear cached health, and background checks run every 15 minutes for enabled configured tools.
 Use **Test credential** for a current fixed read before enabling a configured tool.
+For failed tests, follow the [credential diagnostic guidance](docs/runbook.md#scripted-administrator-sessions) and the [error reference](docs/errors.md).
 Graph tests read at most one user through `entra user list --limit 1`.
 For a new installation, follow [Graph credential setup](#microsoft-graph) and obtain the required permission results and maintainer approval before enabling Graph on a running installation.
 
@@ -551,7 +625,7 @@ Multiple enabled providers appear on both the sign-in page and CLI approval page
 Assign generic-provider users direct artium roles or configure claim rules for tool access.
 Generic rules accept any exact top-level claim name, such as `groups` or `custom.claim`, and match a string or a string in an array against the case-sensitive rule value.
 Dots are literal claim-name characters, not nested paths; numbers, booleans and objects do not match.
-See [generic OIDC verification](docs/verification-p5a.md) for the approved scope split, fake-provider evidence and pending maintainer live acceptance.
+See [generic OIDC verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p5a.md) for the approved scope split, fake-provider evidence and pending maintainer live acceptance.
 
 Provider credentials use the encrypted store; their secrets are never returned in pages, API metadata or audit records.
 Non-secret fields are pre-filled; leave secrets blank to keep them for the same tenant, client and authentication method.
@@ -573,13 +647,13 @@ The users table and signed-in header identify designated accounts.
 Removing designation revokes that account's browser and CLI sessions; demotion also clears designation, and claiming an SSO link removes it.
 When any SSO provider is enabled, only designated local administrators may use password sign-in, password confirmation or password changes, through either browser or bearer routes.
 Fresh installations designate no accounts automatically and keep providers disabled.
-See [break-glass verification](docs/verification-p3c2.md) for local-password policy evidence and [P3 activation verification](docs/verification-p3c2b.md) for activation and complete fake-provider browser acceptance.
+See [break-glass verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p3c2.md) for local-password policy evidence and [P3 activation verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p3c2b.md) for activation and complete fake-provider browser acceptance.
 On an Entra provider page, add, edit or remove role rules mapping an exact, case-sensitive Entra `roles` claim value to an artium role.
 Generic provider pages offer the same rule editor with a claim-name field.
 Each rule's Who matches link opens the enabled, unarchived users whose last successful sign-in claims match that provider, issuer, claim name and value.
 Counts refresh on page reload and include matches for new rules before the next role sync.
 These saved claims are not a live directory query; users without recorded sign-in claims are unknown.
-See the [upgrade runbook](docs/runbook.md#backup-restore-and-upgrade-rollback) for existing-identity compatibility and [claim-rule verification](docs/verification-p5b.md) for local evidence and pending maintainer live acceptance.
+See the [upgrade runbook](docs/runbook.md#backup-restore-and-upgrade-rollback) for existing-identity compatibility and [claim-rule verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p5b.md) for local evidence and pending maintainer live acceptance.
 The target role supplies tool access; rules never grant administrator capability.
 Create roles and grant their tools on **Roles** first.
 Every rule change requires the [confirmation described under browser administration](#browser-administration) and is audited atomically; stale edits require reloading the page.
@@ -601,7 +675,7 @@ Claiming atomically binds the immutable provider identity, consumes the invitati
 Linking preserves the existing user id, username, display name, administrator flag and history, removes the local password and revokes prior browser and CLI sessions.
 An existing identity or username is never automatically linked; expired, revoked, replaced or claimed links cannot grant access.
 Claim, link, role-sync and sign-in audit events commit with the account and session changes.
-See [browser SSO protocol verification](docs/verification-p3b.md) and [SSO reauthentication verification](docs/verification-p3c.md) and [P3 activation verification](docs/verification-p3c2b.md) for fake-provider evidence and pending maintainer live acceptance.
+See [browser SSO protocol verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p3b.md) and [SSO reauthentication verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p3c.md) and [P3 activation verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p3c2b.md) for fake-provider evidence and pending maintainer live acceptance.
 For CLI SSO, set `ARTIUM_AXI_URL` to this server and run `artium-axi login --sso`.
 Open the displayed `/device` URL in any browser, enter the terminal code, choose an enabled provider and complete a fresh sign-in, then review the requesting IP and UTC time before choosing **Approve**.
 Approve only a request you started on a device you control, with a code that matches your terminal; never approve a code someone sends you.
@@ -615,7 +689,7 @@ Approve the returned code through `/device` after a fresh provider sign-in as th
 Poll `/v1/auth/reauth` with the same access token and JSON `{ "deviceCode": "<deviceCode>" }`, waiting the returned `intervalMs` milliseconds between polls, until it returns a recent-auth `ticket` and `expiresAt` instead of `status: pending`.
 Send the ticket in `x-artium-reauth-ticket` on administration requests; it authorizes only the initiating CLI family and cannot extend its lifetime.
 Denial, expiry or revocation prevents ticket issuance; approval codes are single use.
-See [CLI device sign-in verification](docs/verification-p4a.md) for recorded fake-provider evidence and bearer reauthentication coverage.
+See [CLI device sign-in verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-p4a.md) for recorded fake-provider evidence and bearer reauthentication coverage.
 
 ### Audit screen and API
 
@@ -642,6 +716,7 @@ Device approval and refusal emit `device-approve` and `device-deny` events, with
 Each `run-terminal` record uses `action` to report `write` when the native tool journal contains valid JSON object records for that run, or `read` when a successful run leaves its supported journal absent or empty.
 This records journal activity, including mutation intents, rather than guaranteeing that a remote change succeeded.
 Pinned Falcon and LDAP runs report `read` from their inventories' read-only declarations, including normal runs and health checks.
+ADO and AWX use host classification: reads report `read`, successful write calls report `write`, and failed or interrupted writes report `unknown`.
 For tools with native journals, failures without journal records and malformed or unreadable evidence report `unknown`; recovered interrupted runs also report `unknown`.
 See the [API contract](src/shared/api.ts) and [retention and export runbook](docs/runbook.md#retention-and-export).
 
@@ -697,7 +772,7 @@ The optional fields `status: "authenticated"`, `accessExpiresAt` and `familyExpi
 The caller owns expiry policy, refresh serialization across processes and secure persistence.
 Managed mode supports `login`, the home view, `whoami`, `tools`, `tools show`, `doctor` and tool commands.
 `passwd`, `logout` and `setup` are refused before any network call; ordinary sign-in and its server-version warning remain unchanged without the flag.
-Help is available without private channels through `artium-axi --help`.
+Help is available without private channels through `artium-axi --help`; use `artium-axi --managed-session --help` or `artium-axi login --help` for the pipe protocol.
 
 To obtain the first session, run `artium-axi --managed-session login --username <username> --password-stdin` with the password on protected inherited stdin, or `artium-axi --managed-session login --sso` for browser approval.
 Login does not read or require fd 3; it requires a writable private pipe or socket on fd 4 before contacting the server.
@@ -736,6 +811,7 @@ Missing or closed descriptors, invalid JSON and mismatched server bindings fail
 | `ARTIUM_AXI_DATABASE_FILE` | SQLite database path; default `/data/artium.db`. |
 | `ARTIUM_AXI_MASTER_KEY_FILE` | Initial or explicit master-key file containing exactly 32 raw bytes; takes precedence over other key sources. |
 | `ARTIUM_AXI_MASTER_KEY` | Alternative canonical base64 encoding of exactly 32 key bytes. |
+| `ARTIUM_AXI_EXTRA_CA_FILE` | Optional readable PEM bundle of public CA certificates for upstream TLS, including TLS inspection; mounted read-only. Loaded at startup; see the [private CA runbook](docs/runbook.md#tls-inspection-and-private-upstream-cas). |
 | `ARTIUM_AXI_ADMIN_USERNAME` | First-start local administrator username. |
 | `ARTIUM_AXI_ADMIN_PASSWORD_FILE` | UTF-8 file containing the exact first-start password, without an added newline. |
 | `ARTIUM_AXI_TRUSTED_PROXIES` | Comma-separated verified proxy source IP addresses; default trusts none. |
@@ -786,12 +862,14 @@ The runner uses argument arrays without a shell, a restricted child environment,
 Known injected secrets are scanned in raw, JSON-escaped, base64, base64url and URL-encoded output, including beyond capture limits; a match discards both streams.
 Exact-value scanning cannot identify unknown tokens minted upstream.
 Heap and address-space limits are not complete process isolation: descendants starting a new session escape the runner's process group.
-See [runner verification and limitations](docs/verification-s09-10.md) and [secret-scanner evidence](docs/verification-s07.md).
+See [runner verification and limitations](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s09-10.md) and [secret-scanner evidence](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s07.md).
 
 ## Development & Testing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local no-mistakes delivery, container acceptance and the alias deprecation policy.
+
 Use Linux with the [source toolchain](#build-from-source), OpenSSL, Python 3, curl and sha256sum.
-Container acceptance additionally requires Docker and the BuildKit prerequisites described in the [container evidence](docs/verification-s20-21.md).
+Container acceptance additionally requires Docker and the BuildKit prerequisites described in the [container evidence](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s20-21.md).
 `pnpm test:containers` starts a private BuildKit worker with `--privileged`; hosts that forbid privileged containers cannot run this check and must record container acceptance as unverified.
 
 ```sh
@@ -801,7 +879,7 @@ pnpm test:containers
 ```
 
 `pnpm check` verifies generated error-reference freshness, strict type checking, parser/schema inventory freshness, the Vitest suite, compilation and the AXI/distribution checklist.
-See [checklist verification](docs/verification-s46.md) for the fake-only download, authentication, setup and first-call checks.
+See [checklist verification](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/verification-s46.md) for the fake-only download, authentication, setup and first-call checks.
 It refuses unverified host platforms.
 
 The [Vitest configuration](vitest.config.ts) separates unit and integration projects.
@@ -845,4 +923,4 @@ Symlinks, unreadable files and BOM-marked UTF-16/UTF-32 assets fail rather than
 Diagnostics report location (with one-based columns in the original text's UTF-16 code units) and normalized entry number without secret excerpts, and redact labels whose paths match a term using the same folding rule.
 The scan cannot guarantee absence of unknown sensitive values and does not approve publication.
 
-Further operational guidance lives in the [runbook](docs/runbook.md); local implementation and deferred live acceptance are tracked in the [evidence ledger](docs/evidence-ledger.md).
+Further operational guidance lives in the [runbook](docs/runbook.md); local implementation and deferred live acceptance are tracked in the [evidence ledger](https://github.com/knowttl/artium-axi/blob/archive/internal-docs/docs/evidence-ledger.md).