Atlas CLI

First result: read an accessible customer

Before you begin: an installed archive or source-built CLI, a staging account, a delegated token with crm:read, and a customer ID you can access. See installation for downloads and older-archive limits.

1. Follow the quick start below to install and verify the version, then configure the staging URL and token.
2. Run atlas profile read <customer-id>; use ./atlas if running directly from the extracted directory. Replace the placeholder with an accessible customer ID.
3. Inspect status, request_id and data in the JSON, then compare with the customer profile in the web app.

Expected result: A successful read returns status: completed and customer-profile data; this read does not create or change a customer.

If it fails, check atlas auth status and atlas config get base-url, then use troubleshooting for scopes and errors. Continue with the command reference or proposal confirmation workflow.

Quick start

shasum -a 256 -c SHA256SUMS
tar -xzf atlas-cli-<tag>-darwin-arm64.tar.gz
./atlas version
./atlas config set base-url https://atlas.staging.forth.ai
./atlas auth login
./atlas profile read <customer-id>
./atlas library search "warranty terms" --limit 5

atlas version prints the release tag and source SHA. Both must match manifest.json from the same release.

Release status

• MCP server: ready on staging. It publishes eighty-four governed tools; see the MCP server guide.
• MCP server: ready on staging. It publishes one hundred eight governed tools; see the MCP server guide.
• CLI source: ready on the current staging source. Every command in the reference below exists in the current source.
• Downloadable CLI: atlas-cli-v0.1.0-staging.3. This archive predates customer search and customer creation. Build from source to use atlas customer search and atlas customer create …, or wait for the next archive.
• Production: not claimed by this update. Point the CLI at https://atlas.staging.forth.ai.

Auth release operators: the repository-only command bun scripts/auth-authority-release.ts deploy|status|resume|recover --env staging|production --operation UUID registers inactive Auth configuration generations. Mutations require --expected-generation N --candidate-sha SHA; recovery also requires --replace-operation UUID --expected-deployment-id UUID --expected-version-id UUID. Existing Cloudflare privileges, exact release branches and staging reservations apply. See the repository agent lifecycle for migration prerequisites and closed recovery rules. This is not a tenant CLI permission, live policy admission or production delivery claim.

Staging release operators: bun --env-file=/dev/null scripts/staging-migration-readiness.ts SERVICE checks only the configured service-owned staging migration ledger using read-only SELECT queries. It does not initialize a missing ledger or apply migrations. A failed or unverified read blocks publication and cannot use a pending-migration exception. Identified pending migrations require the existing reviewed migration process. This check does not grant permissions or prove a deployment succeeded.

Installation

The private GitHub Release contains atlas-cli-<tag>-darwin-arm64.tar.gz, atlas-cli-<tag>-darwin-x64.tar.gz, manifest.json, and SHA256SUMS.

1. Download the archive for your Mac plus SHA256SUMS into one directory.
2. Run shasum -a 256 -c SHA256SUMS. Stop if any line is not OK; delete the files and download again.
3. Extract the archive and move atlas to a directory on PATH that only you can write to.
4. Run atlas version and compare the tag and source SHA with manifest.json.

Linux and Windows are not supported by the archives. On those platforms, run from source and pass the token through ATLAS_ACCESS_TOKEN.

Configuration

atlas config set base-url https://atlas.staging.forth.ai
atlas config get base-url
atlas auth login      # prompts for a token without echo, stores it in macOS Keychain
atlas auth status     # shows which token source is active, never the token
atlas auth logout

Mint the token in the Atlas portal; the MCP guide shows the request. Remote base URLs must be HTTPS. HTTP is accepted for loopback only.

Command reference

Arguments in angle brackets are required. Every command below sends one REST request to the configured base URL and prints the response envelope as JSON.

atlas team inspect and atlas external call are not the only way a classified external tool gets used: a hire's own run — triggered here through atlas team propose work or observed afterward through atlas team inspect — calls a classified read tool enabled for its role under the same permission-level rules the REST manual's "External tools during a hire's run" describes, capped by the shared maxExternalReadCalls ceiling; a classified effect is never called by a run at any permission level, including auto_pilot.

For example: atlas releases list --kind policy --limit 20, atlas releases search "报价" --cursor "…", and atlas releases read mrel_1. --pretty only indents the same atlas.action.v1 envelope. Missing scope or a revoked token returns the server's forbidden envelope and exit 3; an unavailable upstream returns its failure envelope and does not become an empty result.

# completed: inspect every citation, release field, and next_cursor unchanged
atlas releases list --kind policy --pretty

# an authorised organisation with no current releases
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"completed","data":{"items":[],"next_cursor":null}}

# missing scope or a revoked token: exit 3, never an empty completed result
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"forbidden","error":{"code":"insufficient_scope"}}

# unavailable upstream: preserve the failure envelope and retry convention
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"retryable_failure","error":{"code":"storage_unavailable"}}

Local commands with no REST call: atlas version, atlas config set|get base-url, atlas auth login|status|logout.

The atlas team commands are governed by the AI team release switch as well as by scopes. A platform superadmin controls it at Platform → Feature visibility under the ai-team key, which is hidden until they release it. While it is hidden, every atlas team command — over the CLI, the REST actions behind it, or MCP — is refused with agent_team_restricted, and scheduled Account Manager, Sales Assistant and Pre-sale Assistant work starts nothing new. No other command is affected.

New Account Manager reviews use the pinned complete-json-bytes.v1 source pack: each analysis and approved-draft pass receives only complete authorised records within a 24,000-byte JSON envelope. Drafts receive only approved evidence. If analysis records do not fit, Atlas produces a structurally scoped partial review directly from the retained excerpts and exposes no free-form model prose or draft; if only approved draft evidence is omitted, no draft is prepared. The result records an incomplete-evidence limitation and never presents itself as a complete account review. If no analysis record fits, no review is produced. Run and trace diagnostics report counts only, never copied source bodies. Older pinned runs and Sales Assistant portfolio work retain their legacy source selector.

Repository evaluation operations

Selected-case diagnostics use the existing platform operator session and real agent trial path. They always remain baseline-ineligible, including all-pass or all-60 selections. Full golden remains the default 60 × 3 baseline route. Sealed method trials use this same private queue: Governance retains frozen descriptor, ordinal, billed-run and attempt identities, and creates no Agent TeamStore run. This adds no public launcher or admission path.

bun scripts/eval-campaign.ts start --key diagnostic-a --purpose diagnostic --cases entry-01,entry-03
bun scripts/eval-campaign.ts drain CAMPAIGN_ID
bun scripts/eval-campaign.ts report CAMPAIGN_ID
bun scripts/eval-campaign.ts summary REPORT_ID
bun scripts/eval-campaign.ts compare FROM_REPORT_ID TO_REPORT_ID
bun scripts/eval-campaign.ts start --key full-golden-a

To trial one model route, add --model-route glm_only or --model-route deepseek_only to start, for example bun scripts/eval-campaign.ts start --key route-deepseek-a --purpose diagnostic --cases entry-01,entry-03,entry-05 --model-route deepseek_only. Each trial world's own evaluation organisation is set to that Atlas-managed preset before its first Assistant run; your organisation's model policy is not changed. Any other value is refused before a request is sent. The summary shows the requested route beside the observed model and lists any mismatched trial; a trial whose route is unavailable fails rather than running on another model. A different route needs a new --key: reusing a key with another route is refused as a conflict.

To try a feature switch inside an evaluation only, add --feature-preview KEY to start, for example bun scripts/eval-campaign.ts start --key plan-prefix-on --feature-preview assistant-plan-prefix. The switch is turned on for each trial world's own evaluation organisation before its first Assistant run and removed when the world is cleaned up; your organisation's switches are not changed. A key that is not a registered feature is refused before a request is sent. To measure a switch, run one campaign without the option and one with it on the same deployed Workers, report each, then run compare: the option does not change the comparison compatibility key. A different key needs a new --key.

To compare the two routes, run one full golden campaign per route on the same deployed Workers, report each, then run bun scripts/eval-campaign.ts compare-route GLM_REPORT_ID DEEPSEEK_REPORT_ID. It shows, per route, passed cases on pass@1 and pass^3, the cases that changed (safety cases that regressed are listed separately), p50/p90 time per trial, p50/p90 billed time per model call, and model calls per trial. If the reports differ in anything other than the route, it names the differing field and shows no figures. It reports only; you apply the decision rule and switch the route in Settings → Model keys yourself.

Comparisons require identical pinned selection semantics, corpus, rubric, scorer, target and model-policy identity, plus internally stable evidence. They show fixed/regressed/unchanged per case for pass@1 and pass^3; incompatibilities withhold all deltas. Version 1 stored report bytes and digests remain unchanged. See docs/evaluation-operations.md for recovery and failure evidence.

These Bun commands require an approved Atlas platform operator session — a superadmin on the platform roster — supplied by a private ATLAS_SESSION_COOKIE_FILE. A tenant administrator session is refused with 403 and learns nothing about who holds the target. They are repository operator commands, not delegated-token CLI or MCP capabilities.

bun scripts/eval-reservation.ts status
bun scripts/eval-reservation.ts reconcile OWNER_TOKEN
scripts/deploy-staging.sh governance web
scripts/deploy-web-staging.sh

Campaign starts require a stable idempotencyKey in the JSON body. Repeat the same key and payload to recover missing scheduling; a changed payload conflicts. Campaign status includes frozen admission inventory. A drain request names campaignId.

A reservation never expires into release. Campaign reconciliation requires terminalisation, settled execution and verified pillar cleanup. An operator who does not hold the target reads the holder, the acquisition time and the current settlement blocker rather than an opaque reserved state; the owner token is never disclosed. An operator may attest settlement for a holder who has gone offline, against those same unchanged proofs, and the attesting operator is recorded. Interrupted deployment reconciliation requires explicit subprocess and remote publication settlement evidence plus that reservation's own owner token; the system cannot independently observe a killed local process. Missing reservation state refuses publication. Staging publications carry a freshness guarantee (#2597): a Worker with prebuilt output — atlas-web's SPA bundle — is built inside the shared reservation at the stamped checkout and publication is refused when that build fails, while Workers bundled from source rely on the clean stamped checkout; a /health stamp proves the checkout, never the served bundle. The new migration and API must be established before initial use; no bootstrap bypass is provided.

CLI refusals include the retained campaign ID and recovery details. Recovery preserves the original result, traces and cleanup from an execution settlement without repeating model work; age alone never settles an admitted execution.

Fictional regression packs / 虚构回归用例包

Local administrator authoring: bun scripts/eval-pack.ts scaffold SOURCE PACK_ID en|zh-CN OWNER OUTPUT, then digest DRAFT, validate DRAFT [VERSIONS_ROOT] and publish DRAFT VERSIONS_ROOT. No source conversation is fetched. Product and Sales must record real reviews bound to the exact semantic digest and version. Validation checks format and binding; human repository review verifies authority. The deployed registry is currently empty; the canary draft is unreviewed.

After review and deployment, select a pack with bun scripts/eval-campaign.ts start --key KEY --purpose diagnostic --cases ID,ID,ID --pack-id PACK --pack-version VERSION --pack-digest SHA256. Any identity mismatch refuses before world/model usage. Supplemental reports preserve source/review provenance and remain baseline-ineligible. No runtime uploads or remote MCP authoring tools are supported.

Propose, confirm, reject

Suggest one unsaved method edit

atlas team propose '{"operation":"teaching.suggest","hireId":"amhire_example","revision":1,"teachingSuggestion":{"runId":"amrun_example","excerpt":"No clear question.","expected":"Ask for a decision date."}}' --idempotency-key suggest-example-1
atlas team confirm <proposal-id> --idempotency-key confirm-suggest-1

Confirmation returns one unsaved data.suggestion with bounded proposedInstructions, rationale and inputDigest, plus top-level runId/hireId. Scope defaults to account. Review it before submitting a separate teaching.create. The attempt requires current source access and credits. Replay never generates again; an unrecoverable interrupted attempt returns result_unavailable. A fresh explicit proposal is separately charged. See the REST reference for input limits, organisation restrictions and retention.

1. Propose with a key you choose: atlas customer create propose "Acme" --idempotency-key acme-1. The response is awaiting_confirmation and carries confirmation.id.
2. Inspect: atlas customer create inspect <id>. Check intended_*, evidence, and expires_at.
3. Decide with a second key: atlas customer create confirm <id> --idempotency-key acme-1-confirm, or reject.
4. Re-running a confirm with the same key returns the original result with meta.repeated: true and no second effect.

Proposals expire 15 minutes after creation. Confirming an expired or rejected proposal returns conflict. Task proposals follow the same steps with atlas task ….

REST

Open the REST reference for headers, request examples and response envelopes.

Output and exit codes

stdout is the JSON envelope, one document per command. --pretty indents it. Diagnostics go to stderr. There is no generic --yes; confirmation is always a separate command.

Token handling

• Never pass a token as a command argument. Use atlas auth login or ATLAS_ACCESS_TOKEN. The CLI never prints or logs it.
• In CI and scripts, set ATLAS_ACCESS_TOKEN from the runner's secret store. It takes precedence over Keychain.
• Mint tokens with only the scopes the job needs. Tokens live at most 30 days and can be revoked by an admin.
• Expiry and revocation are decided by the server. The CLI returns the envelope and exits 3.

No analytics, remote fonts, external scripts, or secret-bearing assets are included in this manual.

Troubleshooting

Customer profiles, imports and sampling stages

Customer profile reads include website, background and optional main_markets, brands and products. Organisation and customer-owner authorization still applies. Maintain these facts through REST import or the customer editor.

Task privacy

Self-created, self-assigned tasks default to private, including tasks linked to a customer. Only their assignee can access them; managers and admins have no override. A team task is visible to its assignee, creator and organisation management, never unrelated representatives. These boundaries also apply to filters, source retries, reminders and agent calls. Scheduled shared context excludes private tasks.

Governed named human teams

Named human teams use Auth's shared team functions on every surface. New delegated grants auth:teams:read and auth:teams:write are independent: write permits proposing and confirming a reviewed change, not the read tool. Existing tokens gain no authority; request each grant explicitly through POST /auth/tokens. Minting and every read/propose/confirm/recovery require current active owner/admin membership and the corresponding live members:read/members:write capability. Revoked, expired, role-downgraded or unsupported platform/scheduled/sync credentials cannot act.

MCP: auth_teams_read, auth_teams_change_propose, auth_teams_change_confirm, auth_teams_change_reject. Propose takes the change fields plus idempotency_key; confirm/reject take proposal_id and idempotency_key. CLI: atlas organisation teams read '<json>'; atlas organisation teams propose '<json>' --idempotency-key KEY; atlas organisation teams confirm PROPOSAL_ID --idempotency-key KEY; atlas organisation teams reject PROPOSAL_ID --idempotency-key KEY.

REST action transport: POST /assistant/v1/actions/auth.teams.read, POST /assistant/v1/actions/auth.teams.change, and existing POST /assistant/v1/proposals/:id/confirm or /reject. Send Idempotency-Key for proposals and decisions. Results use the existing atlas.action.v1 envelope and the same Auth team/assignment payload. Team changes are administration proposals; policy holds, expiry, rejection and current authority apply before effects. A proposal is bound to its original principal, organisation, normalized input, revision basis and idempotency key. Delegated tokens cannot override policy; an owner decision remains governed by the existing policy flow.

{"operation":"list","status":"active","limit":50}
{"operation":"team","team_id":"TEAM_ID","limit":50}
{"operation":"assignment","email":"[email protected]"}
{"operation":"create","name":"Sales"}
{"operation":"rename","team_id":"TEAM_ID","name":"Customer Success","expected_revision":1}
{"operation":"archive","team_id":"TEAM_ID","expected_revision":2}
{"operation":"assign","email":"[email protected]","team_id":"TEAM_ID","expected_assignment_revision":0,"expected_team_revision":1}
{"operation":"assign","email":"[email protected]","team_id":null,"expected_assignment_revision":1}

Read lists retain status active (default), archived or all, stable ID/email order, opaque cursor, default 50 and maximum 100 rows. Return next_cursor unchanged. Names are trimmed, nonempty and at most 80 Unicode characters. Unknown/extra fields are rejected. Rename/archive require the current expected_revision; assignment requires expected_assignment_revision and, for a non-null destination, expected_team_revision. Removing an assignment must omit the destination revision. Archive requires an empty active team. No role or global membership mutation is exposed.

Auth commits effect, audit and operation receipt atomically. After a timeout/lost response, retry the same proposal decision/key: recovery returns only the matching original result after live admission and never dispatches again, even if that already-applied proposal subsequently expired. A missing receipt cannot bypass expiry. Reused keys/input or stale revisions conflict; revoked authority is forbidden; unavailable authority/storage is retryable failure, never an empty success. All responses are no-store. Receipt migration 0023_organisation_team_operation_receipts.sql, scopes and Auth producer deploy before Agent adapters; public session team REST stays compatible. The binding-only /internal/teams/actions/read and /change/prepare, /change/execute, /change/recover require exact request/body-bound assertions and have no public alias.

A confirmation timeout may leave Auth still committing. The proposal stays pending; rejection and expiry return a conflict while its outcome is unresolved. Retry confirmation only recovers the original receipt and never redispatches. If no receipt becomes available, the proposal remains pending rather than assuming the effect failed.

Workbench customer analytics through MCP and CLI

The read actions crm.workbench.customer_summary.read and crm.workbench.customer_contributors.read use the existing crm:read grant. Ordinary tenant sessions and explicitly granted delegated tokens resolve current company, assigned-team, self or empty scope in Auth before the CRM query and again before returning. A manager without an active named-team assignment receives explicit empty scope. No team-administration grant or confirmation is needed.

MCP exposes crm_workbench_customer_summary_read and crm_workbench_customer_contributors_read as read-only tools. Summary input is exactly {}. Contributors input is {"metric":"customers","scope_revision":"<scope_revision>","limit":50}, with optional opaque cursor. Metrics are customers, active, at_risk and open_pipeline; limit defaults to 50 and accepts 1–100. Extra fields and caller-supplied organisation, owner or scope hints are rejected.

atlas workbench customers summary
atlas workbench customers contributors '{"metric":"open_pipeline","scope_revision":"<revision>","limit":50}'

CLI uses POST /assistant/v1/actions/crm.workbench.customer_summary.read and POST /assistant/v1/actions/crm.workbench.customer_contributors.read, returning the existing action envelope. Forward cursor bytes unchanged and use the matching scope revision. Each contributor page refreshes all four totals from the same current CRM snapshot as its items; pagination does not freeze a historical snapshot.

Results retain customer-current-book-v1, public scope metadata and evaluated_at. Pipeline amount_by_currency keeps whole currency units in separate groups; unknown_amount_count counts missing amounts. Pipeline items identify both customer_id/customer_name and engagement name/ID. The internal owner roster is never returned.

Responses use Cache-Control: no-store. Invalid input/cursor is 400; credential and authority denials retain 401/403; changed scope is 409 scope_changed (read a fresh summary); an unavailable Auth/CRM service is 503, never a fabricated zero. Platform, scheduled and sync callers are unsupported. Public session CRM routes remain session-only; bearer clients use the governed actions. Deploy the exact Auth allowlists and CRM assertion producers before Agent adapters; no new migration or scope is required.

Knowledge pages and source access

These interfaces are implemented but inactive by default. Exposure requires a complete target census and accepted Product impact review. This reference does not establish staging or production availability.

Offline CLI help reserves this command syntax. Server discovery and proposal admission require a fresh Knowledge-owner readiness check; help output does not establish availability.

atlas pages list '{"limit":50}'
atlas pages read '{"pageId":"PAGE_ID"}'
atlas pages revisions list '{"pageId":"PAGE_ID"}'
atlas pages revisions read '{"pageId":"PAGE_ID","revision":1}'
atlas pages create '<PageCreate JSON>' --idempotency-key PROPOSAL_KEY
atlas pages update '<PageUpdate JSON plus pageId>' --idempotency-key PROPOSAL_KEY
atlas pages decide '<PageDecision JSON plus pageId>' --idempotency-key PROPOSAL_KEY
atlas pages proposal PROPOSAL_ID
atlas pages confirm PROPOSAL_ID --idempotency-key CONFIRMATION_KEY
atlas pages reject PROPOSAL_ID --idempotency-key REJECTION_KEY

Start with a visible page read, then propose the complete JSON input and review it before confirming. After confirmation, inspect page and the readable revision. A contributor editing an approved company page may receive the prior approved projection and revision:null. Inactive page routes return 404.

ekb.page.list, ekb.page.read, ekb.page.create, ekb.page.update, ekb.page.decide, ekb.page.revisions.list, ekb.page.revisions.read.

Personal pages remain owner-only. Company contributors need current knowledgeFiles write permission; review needs knowledge write permission. Ordinary company readers see only the approved revision; view=current requires author or reviewer access. Every read and retry rechecks all sources. Withdrawn, corrected or unreadable sources withhold the entire derivative, including summaries, citations, related titles and counts. Legacy content without complete lineage and Sales-dependent derivatives remain unavailable. The core fallback uses current original passages for lexical retrieval; semantic-only search returns source_unavailable, and unverified vector ranking does not enter model context. Original file titles, passages, downloads and existing permissions are preserved.

Reads require ekb:read. Content-returning delegated writes require both explicitly granted ekb:read and ekb:write. The body idempotencyKey identifies the EKB operation; proposal and confirmation idempotency_key values are separate. Retry with the identical body and key. A 409 conflict requires reading and reviewing the current revision again. A 404 source_unavailable does not identify inaccessible sources; 503 read_unavailable means the read could not be established. Internal adapters may use the signed receiptOnly=true query to recover an existing receipt only; an absent receipt returns 404 and never creates an operation.

Merge customers

Current customer access is required. Reads and review use crm:read; commit, resume and cancel use crm:write, with CRM's current role and customer permissions still enforced. The verified credential supplies the organisation and actor; inputs cannot include org_id. This describes the local candidate capability, not production availability; keep it disabled until the complete journey passes acceptance.

1. Select 2–10 customers. Start a read-only review with customer_ids and optional survivor_id.
2. Edit the returned selection and review the complete selection again. Inspect each value's source and timestamp, conflicts, related records and owner consequences. latest does not replace required explicit decisions. Resolve ties, primary-contact and plan choices, and other blockers first. Values in choices and custom_field_sources are source customer IDs.
3. Show the human the final name, retained original count, owner and access changes, then obtain explicit confirmation. Before sending, durably save one unique request_id, the complete selection, preview_digest and expires_at. Add confirmed:true when committing; a generic --yes cannot skip review.
4. Inspect the same operation until state:complete confirms publication. pending is still processing; blocked needs the stated recovery. After response loss, look up the same request_id instead of creating a new request. Resume only the existing operation_id, without replacement choices.

Expired review or changed data requires another review, never a bypass of preview_digest. Cancellation can be requested only before apply starts; trust state:cancelled. Cancellation is not Undo. Continue recovery after apply has begun. After completion, inspect linked retained read-only originals through merge history. Current access still filters their contents; automatic Undo is unavailable.

atlas customer merge preview '{"customer_ids":["CUSTOMER_A","CUSTOMER_B"]}'
atlas customer merge preview 'FULL_SELECTION_JSON'
atlas customer merge commit 'CONFIRMED_COMMIT_JSON'
atlas customer merge request REQUEST_ID
atlas customer merge status OPERATION_ID
atlas customer merge resume OPERATION_ID
atlas customer merge cancel OPERATION_ID
atlas customer merge history SURVIVOR_ID
atlas customer merge original OPERATION_ID SOURCE_ID

Replace placeholders with complete JSON from review. Commit JSON contains every selection field plus request_id, preview_digest, expires_at and confirmed:true. The JSON request_id is this workflow’s idempotency identity; --idempotency-key is not accepted. Stdout preserves the raw REST protocol object instead of atlas.action.v1. Pending or unknown response exits 6, blocked exits 5, and complete or cancelled exits 0. Exit 6 is not an instruction to resubmit.

Complete fields and REST paths

Keep the same request_id through 409 merge_blocked, preview_stale, preview_expired and request-lookup 404. A concurrent submission can already have been admitted. After a fresh review and explicit confirmation, retry with that same key. On idempotency_conflict, look up the same key and recover the existing operation instead of replacing its plan. Retire the key only after confirmed state:complete or state:cancelled.

Search Atlas

Use atlas.search to find records and content your identity can read. It performs no writes, sends or AI calls. This describes the implementation candidate; it does not establish live deployment or acceptance.

atlas search "电机" --kind customer,task --limit 10

Supply query as 1–100 UTF-16 units without control characters. Optional kinds selects unique categories; limit is 1–20 results per category (default 10). Categories: customer, contact, opportunity, task, work, mail, document, knowledge, chat, assistant.

The atlas.action.v1 envelope carries data.query, items and sections. Every requested category reports complete, unavailable or error. hasMore counts only further accessible matches. A failed category does not erase successful categories. Retry the same query after a failure.

Chat search uses GET /crm/communications/authority/readable?strict=1. A verified denial or empty grant set returns 200 {items:[]}; unavailable or malformed authority and storage failures return 503. Search reports these failures as error with no chat items or counts. It rechecks mailbox grants before returning results; changed grants also retire the category. Existing authority probes without this option retain their empty-set behavior.

Entry retains the existing crm:read scope. Ordinary member sessions carry this transport scope independently of CRM settings permissions; each owning service still enforces its access rules. Tasks additionally require tasks:read; documents and Knowledge require ekb:read. EKB-only or Tasks-only tokens use the existing domain actions. Delegated tokens cannot read private chat or work through this action; those categories retain ordinary-session access. assistant is unavailable until the separately owned identity backend is available. An incomplete or stale mail index returns mail as unavailable; subject or excerpt matches never masquerade as complete body search.

Each result contains kind,id,title and, when needed, subtitle,snippet,customerId,connectionId,threadKey,fileId,sourceId. Titles and subtitles are bounded to 200 units; snippets to 300. Results contain no arbitrary URLs or execution callbacks. Matching precedes limits in the owning service and retains organisation, owner, task privacy, mailbox, conversation-source and Knowledge visibility checks.

After the separately authorized migration 0167_comm_mail_search_text.sql and CRM release, the existing CRM scheduled handler automatically invokes runScheduledMailContentBackfill on configured cron ticks for Inbox-enabled organisations. Each tick processes at most 10 sources within a 5-second budget, using a durable cursor that resumes and retries without blocking later sources. Missing schema leaves this maintenance inactive. Inspect the count-only [crm.cron] mail content backfill log; traversal completion does not prove every body was indexed. Unfinished, failed or stale readable sources keep mail unavailable. New ingestion indexes canonical text; source changes, discard and deletion invalidate stale text. Search never triggers indexing. Verify deployment identity and readable-corpus readiness separately before relying on live search.

Email receipt and legacy backfill sources use unique SHA-256-bound immutable artifact keys. Deploy the producer, attachment/reply reader compatibility and version-2 index/backfill together. Legacy version-1 indexes remain unavailable until rebuilt. Backfill freezes the current retained snapshot; it cannot reconstruct bytes already overwritten by the historical mutable-key race. Original legacy blobs are retained. Any rollback must preserve reader compatibility with the new keys; prefer a forward repair.

Automatic Assistant capabilities

New named assistants automatically use Atlas’s existing task-time capability resolution: enabled organization skills, callable connected plugin tools, built-in functions and authorized knowledge retrieval. Published organization guidance and the current user’s active memory resolve through their existing owners. No manual assignment, installation, new permission or memory publication is performed.

The directory advertises setupSchema: atlas.assistant-setup.v1. A clear bilingual job name infers focus; an unclear or conflicting name returns 400 assistant_purpose_required before a proposal. Supply optional identity.purpose as one trimmed description of 1–400 characters without control characters. Review the effective focus, then explicitly confirm. A saved custom identity may include setup: {mode: automatic, focus, source: name|clarified}; legacy identities omit it. Avatar-only edits retain focus; a changed name infers again or asks for clarification, and an explicit purpose overrides it. Focus steers task skill selection as untrusted user data; it grants no authority.

Shared governance traces retain run identity, usage and policy metadata without private conversation content, plans or tool inputs and outputs. Owner conversation history remains available.