@knowttl/artium-axi 0.0.4 → 0.0.6

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 and Azure DevOps 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,7 @@ 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 personal access token (PAT). | `project list --limit 1`. |
 
 #### Falcon
 
@@ -224,14 +225,15 @@ Falcon's fixed `auth status` test reports local credential resolution, so also r
 
 #### 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.
+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.
 
@@ -325,7 +327,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
 
@@ -337,9 +339,11 @@ The native Kerberos provider and its installation script are unnecessary for thi
 
 Obtain a dedicated directory identity with read access only, its bind DN and password, and a directory URL whose certificate can be verified.
 At `/admin/tools/ldap-axi`, enter `url`, choose `auth=simple`, and enter `bindDn` and the password value in `bindPassword`.
-Use `ldaps://<directory-host>:636`, or `ldap://<directory-host>:389` with `startTls=true`.
+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.
@@ -352,6 +356,29 @@ LDAP is read-only by design and has no editable native write settings.
 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.
+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.
+PAT authentication is available now; client ID and secret authentication is a separate integration phase, with no device flow.
+Local fake-service checks do not establish live organization acceptance.
+
 ### Build from source
 
 The source toolchain requires Node **24.11 or later** and **pnpm 10.22.0**.
@@ -369,7 +396,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
 
@@ -385,7 +413,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. |
@@ -394,6 +422,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
@@ -430,7 +461,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 and Azure DevOps, 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.
@@ -513,21 +544,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.
 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.
 
@@ -550,7 +589,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.
@@ -572,13 +611,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.
@@ -600,7 +639,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.
@@ -614,7 +653,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
 
@@ -641,6 +680,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 uses 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).
 
@@ -696,7 +736,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.
@@ -735,6 +775,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. |
@@ -762,7 +803,8 @@ Fake-service results do not establish live platform permissions or production re
 Never put tokens or keys in arguments, source files, images or logs.
 The server refuses the removed development-authentication settings `ARTIUM_AXI_DEV` and `ARTIUM_AXI_DEV_TOKEN_FILE`.
 
-Local passwords use Argon2id, require 15 to 128 code points and at most 512 UTF-8 bytes, preserve spaces and Unicode, and reject exact matches in the bundled common-password list.
+Local passwords use Argon2id and accept any non-empty password of at most 512 UTF-8 bytes, preserving spaces and Unicode.
+The byte cap bounds input to native hashing; there are no minimum-length, character-count or common-password rules.
 Access tokens last one hour within an 8-hour SSO CLI family or a 12-hour local CLI family; refresh-token reuse revokes the family.
 Password changes revoke existing CLI tokens and browser sessions.
 See [browser administration](#browser-administration) for session management and user archival.
@@ -784,12 +826,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
@@ -799,21 +843,26 @@ 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.
+Only the integration project loads the [reduced-cost password hashing setup](test/fixtures/integration-setup.ts); local authentication unit tests and the native smoke retain production hashing costs, as does the dummy hash used for missing accounts.
+
 | Command | Scope |
 | --- | --- |
 | `pnpm lint` | Static TypeScript checking. |
 | `pnpm test` | Inventory/schema freshness checks and the full Vitest suite. |
 | `pnpm build` | Server compilation and standalone client bundle. |
 | `pnpm test:security` | Tests whose names contain `security`. |
-| `pnpm test:containers` | Mandatory fake-only runner, walking-skeleton, Graph headless and fake-service container acceptance. |
+| `pnpm test:containers` | Fake-only runner, walking-skeleton, Graph headless and fake-service container acceptance. |
 | `pnpm test:browser` | Real admin pages in an isolated Chrome session through `chrome-devtools-axi`, against the local fake browser harness. |
 | `pnpm test:containers --measure-cache` | The container block plus an identical-input warm runner build measurement. |
 | `pnpm errors:generate` | Regenerate the error reference after changing the catalogue. |
 
-The container block builds before probing, emits head/input/output evidence and timings, and removes its uniquely owned test images and private BuildKit cache.
+The container block builds before running independent acceptance phases concurrently, emits head/input/output evidence and timings, and waits for every phase before removing its uniquely owned test images and private BuildKit cache.
+The [gate configuration](.no-mistakes.yaml) owns the paths that require container acceptance and the CLI, documentation, workflow and skill-only exemptions.
+Every release requires container acceptance under the [release prerequisites](docs/runbook.md#npm-client-releases).
 Do not touch shared Docker resources or use real service credentials.
 Changed relevant inputs invalidate earlier container evidence.
 Upstream pins and integrity records live in [tools/package.json](tools/package.json), [tools/integrity.json](tools/integrity.json) and [tools/falcon-source.json](tools/falcon-source.json).
@@ -827,7 +876,7 @@ Before publishing a candidate, commit and build it, then set `ARTIUM_AXI_HYGIENE
 pnpm hygiene:check
 ```
 
-The UTF-8 list contains one literal term per line, matched case-insensitively after trimming whitespace; blanks and duplicates are ignored.
+The UTF-8 list contains one literal term per line, matched after trimming whitespace using context-independent Unicode simple case folding; blanks and case-equivalent duplicates are ignored.
 Unset, unreadable, empty or in-tree lists fail.
 Never copy real terms or the list into this repository.
 Record only its revision or SHA-256, candidate commit and pass/fail result.
@@ -835,7 +884,7 @@ Record only its revision or SHA-256, candidate commit and pass/fail result.
 The check scans tracked, untracked and ignored files, generated output and every commit message reachable from `HEAD`, excluding only `.git` metadata and installed `node_modules` directories.
 Supply intended release assets outside the checkout as additional `pnpm hygiene:check` arguments, keeping the list outside those directories too.
 Symlinks, unreadable files and BOM-marked UTF-16/UTF-32 assets fail rather than reducing coverage; convert unsupported encodings to UTF-8.
-Diagnostics report location and normalized entry number without secret excerpts, and redact labels whose paths match a term.
+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).