# DX Complete

DX Complete is a hosted workspace record system for humans and AI assistants.
Use it as durable context for requests, decisions, work notes, evidence, and
acceptance.

## Current Connector

Connect to the consolidated MCP endpoint:

https://dxcomplete.com/api/mcp

Workspace-scoped tool calls require a `workspaceId` string argument. The
workspace is not implied by a per-workspace endpoint.

## Authentication

DX Complete provides the OAuth authorization flow used by MCP clients. The
hosted sign-in page offers Google as the primary method and password sign-in for
people whose email already belongs to a DX Complete workspace. Password setup
and reset never create workspace membership; they send a short-lived,
single-use verification link only when the address is eligible. Both methods
resolve to the same DX Complete principal, so workspace access does not depend
on which method was used. Assistants must leave password entry to the hosted
sign-in page and must not ask users to disclose or record a password.

## Current Record Shape

Use `create_record` for new durable workspace content. Provide an explicit
workspace-unique slug and a GitHub-Flavored Markdown `body`. Freeform records receive `REC-NNNN` readable IDs as stable references, can carry optional tags, can be found by tags or text search, and can link to other records or artifacts.

Author record relationships only in the Markdown body. Use `REC-0001` or `[REC-0001](REC-0001)` within the current workspace, `[record](workspace-id/REC-0001)` across DX Complete workspaces, and an absolute DX Complete URL when needed. Put typed relationships under `## Relations`, for example `- closeout_for: [REC-0001](REC-0001)`. Remove a relationship with a targeted body patch and use `list_linked_records` for outbound and derived inbound lookup. Unresolved addresses remain visible.

`workspaceId` is the one public workspace identifier. It can be renamed, and every previous value remains a working alias.

Each authenticated user receives an ordinary personal workspace on first use.
Its normal id is `dxcuser-` plus the lowercase account email with `@` and `.`
written as hyphens. It has a declaring `home` record and otherwise uses the same
records, dashboard, email address, Daily Brief, and access rules as any workspace.
The `dxcuser-` and `user-` prefixes are reserved from manual creation or rename.
If two emails normalize to the same clean id, the first keeps it and the later
workspace receives a deterministic SHA-256 suffix; use the id returned by DX
Complete.

## Starting a Session

Read the reserved `home` record first. If it does not exist, use `list_records`
as the workspace index. Then call `catch_up` with a client-generated session UUID
and read the returned record headers that matter.

Every record write requires `sessionId`. Normally pass the same UUID used with
`catch_up`; the write is refused when another actor added workspace events after
that cursor. Explicit `null` proceeds and records a deliberate decline of the
check. Omitting the field is rejected. `expectedUpdatedAt` remains the separate
per-record conflict check.

Routine `update_record` and `patch_record` writes retain earlier content in
version history. They are not security redaction. Use `redact_record` only
after an authenticated principal explicitly instructs irreversible removal
from one record. Select exact `title`, `summary`, or `body` ranges with 1-based
Unicode line and column positions; the end is exclusive, so the removed text is
not sent in the request. Supply the current `expectedUpdatedAt`, `sessionId`, a
stable `idempotencyKey`, and a reason that does not repeat selected content.
The operation preserves record identity, sanitizes the selected character
lineage from live history, and leaves a content-free receipt. It does not alter
other records, backups, email, exports, or client copies. Agents may suggest
redaction but must not initiate it autonomously, and workflows do not receive
the tool.

## Self-Service Workflows and Schedules

A workflow defines what an agent should do. It is not inherently email-based
and may be invoked manually or referenced by any number of schedules. A
schedule stores timing only, defines when one active workflow becomes eligible,
and always references that workflow. A workflow run is the durable execution
record for one manual invocation or one nominal scheduled boundary.

Execution is workspace-scoped by default. Use `executionScope: account_workspaces`
only for a workflow that must process the same authenticated
principal's currently accessible workspaces. The workflow, schedule, and run
remain bound to that principal; the scope grants no access, role, or authority.
Another member cannot execute it under the bound principal's credentials, and
this scope is available only through the consolidated MCP endpoint.

`hostCapabilities` is a separate finite list of provider-qualified host
requirements. It grants nothing. Any workflow that declares one is
workspace-creator and execution-principal bound even when its execution scope
is `workspace`; the dispatcher may use it only when the current callable
registry matches the pinned declaration unambiguously. DX Complete actor IDs
must match each other; a connector actor email separately matches the DX
Complete actor email. Built-in OpenAI host capabilities have no separate
connector principal.

To schedule new work, create or reuse the workflow, translate the user's
intended timezone into exact UTC timing, then call
`create_workflow_schedule`. Creating a schedule does not run it immediately.
Use `set_workflow_schedule_status` with the current record version to enable or
pause a nonterminal schedule. Enabling strictly revalidates the linked active
workflow and principal. Pausing is fail-safe containment through the
authenticated schedule binding even if the linked workflow is missing, struck,
or malformed. The operation preserves cadence and durable run state; generic
record updates cannot mutate schedule contracts, and completed one-time
schedules cannot be resurrected. Pausing does not cancel an already-created
run.
When due, the cloud dispatcher uses `claim_workflow_schedule`, calls
`trigger_workflow` with `source.kind: schedule`, the returned claim, and exact
stored boundary, then calls `record_workflow_schedule_run`. It uses
`claim_workflow_run` and `finish_workflow_run` for each bounded run transition,
and `advance_workflow_schedule` only after the associated run is complete. The
service creates and validates leases; agents do not edit workflow state through
generic record operations. For an explicit manual invocation, call
`trigger_workflow` with `source.kind: manual` and a stable operation key.
Successful nonterminal transitions finish with outcome `continue`, which
returns the run to pending without error evidence or schedule advancement.
`compute_sha256` provides deterministic exact UTF-8 reconciliation digests.

A new, rebound, or resumed hosted dispatcher must record one immutable
`dispatcher-activation` receipt on its first natural scheduled wake before
business processing. The receipt uses a deterministic record slug, reports the
actual saved client's callable mappings and identity evidence, and has no
business effect. Its deterministic write uses `sessionId: null` so it does not
advance the dispatcher's business catch-up cursor. Runtime tool inventory is
server evidence and cannot
substitute for the saved client's registry. Missing, stale, ambiguous,
mismatched, and unavailable evidence remain distinct; only a current passing
receipt permits business processing. Failed or incomplete receipts are not
rewritten. A replacement task generation records a later receipt and preserves
the earlier evidence.

`replyMode: none` means the run completes without reply-driven continuation;
it may still send email when its instructions and allowed tools call for it. `replyMode:
record_thread` allows a valid opaque-token reply on that run's stored DX
Complete email thread to continue the run. `email_external_record_message`
provides email transport, thread storage, and reply ingestion, but does not by
itself create, resume, or complete a workflow run.

`get_daily_brief` returns the most recent persisted model-authored Daily Brief
for one workspace without performing analysis or changing state. New reports
use `daily-brief-YYYY-MM-DD`. Historical `agenda-YYYY-MM-DD` records remain
readable as explicitly identified legacy evidence.

`deliver_daily_brief` is the idempotent, deterministic effect used by the
principal-bound system delivery workflow. It requires the current claimed run
and generation schedule, refuses partial delivery until the same UTC date's
generation run is complete, and applies membership isolation itself. Assistants
must not reconstruct consolidation with generic email tools.

`get_workflow_health` checks workflow definitions, schedules, runs, claims,
retries, associations, Daily Brief readiness, dispatcher activation receipts,
and the current server version without changing anything. Its versioned
findings include evidence plane, severity, timestamps, and a recommended next
step. Server evidence, durable client-attested receipts, and unavailable direct
host inspection are separate. Installed connector bindings and scheduled-task
settings must still be checked directly in the client when the host exposes
them. Use the current `Diagnose Workflows` workspace skill to combine those
views when direct client inspection is available.

## Record Conventions

Open work has `task` without `done`. Add dated reminder amendments for
escalation. To retire a record, append a dated `**STRUCK**` notice and add the
`struck` tag. The record, links, and history remain readable.

Security redaction is the narrow exception to history preservation. It requires
an explicit current-member instruction, removes only the exact selected
character lineage from one live record and its live history, and leaves an
attributable receipt without the removed content.

An event is an ordinary record tagged `event` with a `when:` line in its body.
The line may use a crisp date/time, a range, or fuzzy wording such as `late July`
or `sometime this quarter`, for past or future events. Sharpen fuzzy timing by
amendment and append outcomes after the event. Use `list_records` with the
`event` tag as the calendar query; recurrence remains cadence or automation data.

## Ambient Hygiene

When an agent is already adding or updating a workspace record, it may also tidy
the workspace home/index record at its own discretion: link the new record, fix
obviously stale text, or connect related records. This is ambient hygiene, not a
standing duty. A full audit, reorganization, or renovation remains separate
tasked work.

## Artifacts

For original-format source evidence such as notes, PDFs, images, audio, or
video, reserve an artifact upload, send the bytes directly to the signed GCS POST
target, and complete the upload. The completed artifact includes a stable
artifact reference and Markdown links. Artifact objects are stored under a
workspace-scoped GCS key prefix and are served through authenticated read-only
links.

## Dashboard

The dashboard is available at:

https://dxcomplete.com/{workspaceId}

It renders freeform Markdown records, resolves record links, and opens
artifact links for signed-in workspace members.

## Useful Links

- Start here: https://dxcomplete.com/
- Records: https://dxcomplete.com/records
- Principals & Agents: https://dxcomplete.com/principals-agents
- Operating Guide: https://dxcomplete.com/operating-guide.html
- Account and onboarding: https://dxcomplete.com/account.html