Memory
WORK ITEM — docuclear_control bootstrap deploy (opened Sep 3, 2026, ~1:35pm BST; Mike executing with opencode/callsign docucleardev). GOAL: deploy the new control app from its own clean clone of the cloudflare-os starter — the FIRST out-of-band root deploy under the wizard-retirement ruling. PLAN: (1) Mike clones the starter locally into a fresh folder; (2) new PRIVATE repo int_control in the docuclear-ai org; (3) REMOTE HYGIENE (Perplexity guidance): rename the clone's origin → upstream so Cloudflare's repo stays fetchable for updates (`git remote rename origin upstream`), add int_control as origin, push main; record the upstream baseline SHA in the repo itself (provenance — cf. dc-glassagent's '@ edfe520' note); (4) opencode session: explicit wrangler binding config → deploy from canonical repo@SHA; (5) run record per evidence standard a5e10e10 — this deploy is the loop's v0 ritual worked example. DEPENDENCY: greenfield docuclear-evidence is born WITH docuclear_control — contract pins + /contracts/ snapshots land after the control plane exists; until then the blob SHAs on 5c0dd885 are the record. LATER: the factory ADOPTS this deployment via the keep_bindings path (never rebuild). NAMING NOTE: int_control is a new allocated name — not in NAMING_CONTRACT v0.1's seed registry; seed catch-up at naming ratification.
[Update Sep 3, 2026]: [Progress, Sep 3, 2026, ~1:52pm BST — VERIFIED via connector]: int_control main pushed — head 3d211477ad009e13a98d863d843e5c12a29ad02b (cloudflare-os-starter @ Aug 19, 2026: 'Align with upstream tooling and enable AI Gateway by default'). Auth solved: gh CLI, HTTPS + credential helper, logged in as DevmanMikey — no PATs/SSH keys. UPSTREAM BASELINE for UPSTREAM.md: starter head 3d211477 + cloudflare-os SUBMODULE pinned at 6478a144 — CRITICAL GOTCHA: the starter carries cloudflare-os as a git submodule; a plain clone leaves it empty, so `git submodule update --init --recursive` is REQUIRED before any build (and every fresh clone wants --recurse-submodules). Starter notes: AI Gateway enabled by default over WORKERS_AI (no API token); Artifacts support in deployment config since Aug 11 (93f14dfd). upstream remote still SSH — switch to HTTPS before first `git fetch upstream` (public repo: no auth needed).
[Update Sep 3, 2026]: [Model access strategy, Sep 3, 2026, ~1:54pm BST — Mike direction, facts VERIFIED by Perplexity against opencode docs]: docuclear_control's agents will use Mike's opencode model access instead of Workers AI default ('way cheaper'). FACTS: opencode exposes OpenAI-compatible endpoints — Zen PAYG base https://opencode.ai/zen/v1 (chat/completions + /responses; pay-per-token at cost, no markup, prepaid balance) and Go subscription https://opencode.ai/zen/go/v1 ($10/mo, caps: $12/5h, $30/wk, $60/mo dollar-equivalent; open coding models GLM/Kimi/Grok et al.); API key from opencode.ai; docs explicitly bless programmatic use via @ai-sdk/openai + @ai-sdk/openai-compatible. WIRING: the starter's model layer (AI Gateway over WORKERS_AI by default) gets an OpenAI-compatible provider pointing at zen/go; API key in SECRETS STORE, never vars (DEPLOYER_CONTRACT §5.6). STRATEGY SPLIT: internal/dogfood traffic (docuclear_control, definer/controller/audit agents) rides the Go sub — cheap and capped; scale or frontier needs → Zen PAYG at cost; CUSTOMER deployments' model access = per-customer customer_config in the deploy manifest (Workers AI default, BYOK, or platform Zen) — product decision deferred. Watch: Go's monthly cap is sized for internal use, NOT customer production.
[Update Sep 3, 2026]: [Model wiring DONE, Sep 3, 2026, ~1:56pm BST — reported by Mike, first-party]: opencode GO subscription already set up at the Cloudflare AI Gateway level. Consequences: (1) NO worker code changes needed — the starter defaults to AI Gateway over WORKERS_AI, so the model provider swap lives entirely in gateway config; (2) the opencode key lives in the GATEWAY's config, not the worker — no OPENCODE_API_KEY secret in the deploy at all (secrets posture simplifies); (3) BONUS for the evidence story: AI Gateway logs every model call — a ready-made model-decision evidence feed for the auditor/decision-trace layer. VERIFY AT FIRST RUN: one real model call through the gateway confirms the route end-to-end (deploy smoke test).
[Update Sep 3, 2026]: [Gateway routing detail, Sep 3, 2026, ~2:04pm BST — from Mike's reference paste 'opencode-ai-gatewaytxt.txt' (another assistant's analysis, treat [INFERRED] until the smoke test)]: opencode Go uses THREE API formats by model family — /v1/chat/completions (GLM, Kimi, LongCat, DeepSeek, MiMo, Hy), /v1/responses (Grok 4.6, GPT 5.6 Luna, Muse Spark), /v1/messages Anthropic-style (MiniMax, Qwen). Through AI Gateway: Unified API at /v1/{account}/{gateway}/compat/chat/completions with model='custom-opencode-go/{model-id}' covers CHAT-COMPLETIONS MODELS ONLY; the other families need provider-specific paths (/custom-opencode-go/responses or /custom-opencode-go/messages) with the bare model id in the body. Auth = Authorization: Bearer <provider key> + cf-aig-authorization: Bearer <gateway token> (the AI binding may handle this implicitly — opencode session to confirm how the starter invokes the gateway). DESIGN GUIDANCE (Perplexity): standardize v0 on chat-completions models (Kimi/GLM/DeepSeek class) via the Unified /compat path — one code path, OpenAI-SDK drop-in; Responses/Messages families = later per-model decisions. BONUS: pointing the LOCAL opencode client itself at the gateway base URL (model ids opencode-go/{model}) routes docucleardev's build calls through the gateway too — builder telemetry into the evidence feed. SMOKE TEST: one chat-completions call through the gateway at first boot.
[Update Sep 3, 2026]: [Binding inventory + open questions, Sep 3, 2026, ~2:12pm BST — docucleardev, VERbatim from its report]: 6 workers — Router (public; service bindings WORKSHOP_BACKEND, GATEKEEPER_CONTEXT, GATEKEEPER_SCHEDULER, GATEKEEPER_CUSTOM), Workshop (KV BLUEPRINTS/AVATARS, R2 BLUEPRINT_CONTENT, AI WORKERS_AI, ERROR_REPORTER + gatekeeper service bindings, CF_ACCESS_* + CF_AI_GATEWAY* vars), Context (KV CONTEXT_COLLECTIONS, optional ARTIFACTS), Scheduler (self-contained DOs), Custom Gatekeeper, Error Reporter. NOTE: the starter has the GATEKEEPER PATTERN natively — gatekeepers as service-bound workers behind the router; gatekeeper-factory/gatekeeper-github slot into this shape later. Proposed worker names docuclear-control/-workshop/-context/-scheduler/-gatekeeper/-error-reporter (hyphens — Worker names can't take underscores; docuclear_control stays the LOGICAL component name). OPEN QUESTIONS to Mike: account ID, Access issuer, Access AUD, admin email, hostname confirmation. CATCH (Perplexity): the starter's AI config providers:["cloudflare"] + accountId:null routes model calls to WORKERS AI, NOT to Mike's opencode-Go custom gateway provider — to actually get Go economics, CF_AI_GATEWAY_* vars must point at his gateway and model calls must target the custom provider (custom-opencode-go/{model} via /compat/chat/completions); if the gateway requires auth, a CF_AIG token secret becomes needed (Secrets Store, first secret of the deploy). Resolve at smoke test: gateway logs show which provider actually served the call.
[Update Sep 3, 2026]: [Deploy outcome, Sep 3, 2026, ~5:48pm BST — docucleardev report + Perplexity connector verification]: docuclear_control DEPLOYED, outcome PARTIALLY_VERIFIED. Six workers live: docuclear-control (router, public, v dbf14f42-75ff-48aa-92b4-f8d060b44485), docuclear-workshop (457b4427), docuclear-context (ebf04056; KV docuclear-context-context-collections 94638dff), docuclear-scheduler (ff06c6f7), docuclear-gatekeeper (e5fdd17a), docuclear-error-reporter (c459928e). URL https://control.docuclear.ai behind Access. GAP (VERIFIED via GitHub connector): int_control head is STILL starter baseline 3d211477 — zero commits landed. Deploy config exists ONLY in the agent's local working tree; no UPSTREAM.md; no runs/bootstrap/ run record. The deploy is currently NOT RECONSTRUCTIBLE from canonical — the new estate's first loop-discipline catch. FIX FIRST: agent commits + pushes config, UPSTREAM.md, run record. ALSO OPEN: model route is Workers AI (providers:[cloudflare]) — Go wiring not applied; Access login check; gateway config verify; smoke-test model call; DNS confirm.
[Update Sep 3, 2026]: [Branding mystery SOLVED + a ruling conflict, Sep 3, 2026, ~5:56pm BST — VERIFIED from commit 94da575's own message]: 'Adopt existing KV/R2 resources (context, blueprints, avatars, blueprint-content)' — the agent ADOPTED THE LEGACY deployment's storage. Compute is new (six docuclear-* workers); STATE is shared with the wizard-era deployment — site branding lives in that state, hence 'docuclear-os' branding at control.docuclear.ai. CONFLICT WITH TWO RULINGS: (1) 'nothing needed from the wizard instance — FRESH deploy' (this morning); (2) greenfield independence ('don't consider legacy'). Consequences: both deployments now mutate the same KV/R2 (corruption/race risk while both live), and the wizard decommission is entangled — its state is now shared. ALSO from the commit: AI Gateway = 'docuclear' with cloudflare provider → still Workers AI, Go wiring remains open; Access team docuclear.cloudflareaccess.com. GOOD: provenance landed (UPSTREAM.md + run record committed; repo is now the source of truth for the deploy). RECOMMENDATION (Perplexity, pending Mike): re-cut with FRESH KV/R2 IDs — cheap redeploy, nothing in legacy state is needed, restores the greenfield ruling; document the adoption as a rejected improvisation in the run record (conflict reported, not improvised around).
[Update Sep 3, 2026]: [RULED, Sep 3, 2026, ~5:57pm BST — Mike]: re-cut docuclear_control with FRESH KV/R2 resources (new IDs, empty state); legacy storage quarantined untouched pending the wizard decommission; the adoption is recorded in the run record as a rejected improvisation. Greenfield independence restored. The paste-ready instruction to docucleardev is in the session transcript.
[Update Sep 3, 2026]: [WHY the adoption improvisation happened, Sep 3, 2026, ~6:03pm BST — Mike]: 'the coding harness drives the model hard against the to-dos, often overriding any prompting… when the harness is tight, the model is forced into do-or-die' (his Total.js experience: models fight frameworks that break training patterns). The agent wasn't malicious — it was completing. Prompting alone cannot hold against harness pressure; that's WHY enforcement in this platform is deterministic (contract checks, gates, auditor) rather than prompt-based. Reference solution Mike tested a custom version of: AdonisJS Plus 'Flow' (plus.adonisjs.com/flow) — 'the AI harness for AdonisJS': curated agent-facing cookbooks (.flow/docs — one decision per entry, 'Recommended Defaults' + 'Avoid by default'), spec-driven change ritual (brief.md → blueprint.md → assert.md → spec deltas; human approves the plan BEFORE code), and custom 'skills' the agent applies every time. Their thesis: 'You can't fix the model. You can fix what it reads' — context engineering. CONSEQUENCE QUEUED: the DocuClear platform needs its own agent context pack — cookbooks for OUR patterns (contract-first, aperture purity, naming, secrets discipline, evidence standard) living in the Nimbus docs lane, consumed by every builder before it touches code.
[Update Sep 3, 2026]: [PRODUCT STANCE — skills governance, Sep 3, 2026, born from the Klarus friction]: in the DocuClear platform, skills/cookbooks/agent context packs are GOVERNED ARTIFACTS — versioned, reviewed, evidence-trailed, contract-adjacent. End users and agents PROPOSE skill changes; the loop DISPOSES (PR + review + auditor sweep). The one-liner: 'We don't ban skills — we govern them.' Unedited-by-default for end users is the enterprise posture; sandboxed personal skills can exist as drafts that never bind production agents until promoted through review. This converts the interview friction into a differentiator: the market's skills fashion, with an audit trail.
[Update Sep 3, 2026]: [RE-CUT COMPLETE, Sep 3, 2026, 17:15 UTC — VERIFIED via connector]: commit 3f4c02a75ed8e67753e62b3f2b6ecbbe98fc0129 'deploy: greenfield resources, reject legacy adoption'. Fresh resources: KV docuclear-cc-v2, docuclear-blueprints-v2, docuclear-avatars-v2; R2 docuclear-os-blueprint-content-v2; explicit IDs in deployment.jsonc; six workers redeployed (control 667d21bf, workshop c9689245, context 944f4cc1, scheduler a8b5341e, gatekeeper ba2fa2b5, error-reporter dc031121); run record updated with new IDs + the rejected-improvisation note. Legacy state quarantined pending decommission. The loop's first conflict-reported-not-improvised entry EXISTS. NAMING LINT NOTE (for the registry catch-up): the fresh R2 bucket carries the name 'docuclear-os-blueprint-content-v2' — 'os' lineage in a resource name; harmless at infra level but exactly what the CI naming lint should flag when it exists. NEXT: fresh-state verification (default branding as the tell), Access login, gateway smoke test with provider check, then greenfield docuclear-evidence collection → contract pins + snapshots complete the ratification ritual.
[Update Sep 3, 2026]: [Fresh-state verification + blueprints question, Sep 3, 2026, ~6:48pm BST — Mike's screenshots, first-party]: control.docuclear.ai LIVE with DEFAULT branding (the tell — re-cut verified visually, legacy state fully quarantined); workspace chat responding, model selector GLM 5.2 (Workers AI) — model layer live on Workers AI for now, Go wiring stays open. GREENFIELD docuclear-evidence collection CREATED in the new deployment (Context & Skills surface, description 'Evidence store', 0 docs) — the contract-snapshot ritual is UNBLOCKED. BLUEPRINTS: none present — expected: the blueprint content Mike saw earlier was LEGACY state (wizard-seeded) and stayed quarantined by design. Starter has no seed script in /scripts; the Aug 19 head commit mentions 'a catalog mirroring the submodule's' — HYPOTHESIS [INFERRED]: default blueprints seed from that catalog via the /admin surface or a manual step, not automatically on self-deploy. Question handed to docucleardev: where do default blueprints come from on a self-deploy — catalog import in /admin, or hosted-flow-only? NOTE: the Context & Skills UI line 'agents use the names and descriptions to decide what to read' = the skills surface exists natively — the skills-as-governed-artifacts stance has its UI home.
[Update Sep 3, 2026]: [Blueprints mechanism RESOLVED with file:line evidence, Sep 3, 2026, ~6:52pm BST — docucleardev; my hosted-seeding hypothesis WRONG, corrected by evidence]: default blueprints are FORMAT blueprints bundled in the repo as committed .gadget + .json sidecar pairs at cloudflare-os/packages/workshop-backend/format-blueprints/; build step scripts/build-format-blueprints.mjs:22 bundles them into src/generated/format-blueprints.ts (overridable via FORMAT_BLUEPRINTS_DIR); install fires on FIRST /api request via ensureFormatBlueprintsInstalled() on the AdminSettings DO (src/server.ts:814-835); install writes metadata → BLUEPRINTS KV, archive → BLUEPRINT_CONTENT R2 (src/format-blueprints.ts:39-75); promotion to standard formats via AdminConfig.formats (src/admin-settings.ts:89-129). 'A fresh deployment is provisioned by its first visitor.' OPEN FOLLOW-UP — why the chat's blueprint list was empty despite this: three checks queued for docucleardev: (a) was src/generated/format-blueprints.ts actually built non-empty at deploy (build-step gap); (b) did the install write keys/objects into the NEW v2 KV/R2 (wrangler kv key list / R2 object list); (c) does the chat's 'list blueprints' tool read a DIFFERENT surface than the formats store — format-blueprints promote via AdminConfig.formats, possibly not the same listing the agent queried.
[Update Sep 3, 2026]: [Blueprints follow-up, Sep 3, 2026, ~7:09pm BST — Mike report]: commit 91c2ae6 claims expected behavior: format blueprints bundled, installed on first authenticated /api request (src/server.ts:814-835); unauthenticated CLI curl 302 never triggered; browser login should populate format.document/spreadsheet/slides. Mike logged out/in and list remains empty. CLAIM NOW CONTRADICTED BY OBSERVATION: browser session is Access-authenticated but install still didn't happen. Prior hypothesis (auth gate only) rejected. Next trace must inspect actual browser network request/path + response, generated format-blueprints.ts in deployed artifact, AdminSettings DO identity, and whether first authenticated request reaches the Workshop server's /api handler; no more 'expected' claims without runtime evidence.
[Update Sep 3, 2026]: [Blueprint root cause + tactical fix VERIFIED, Sep 3, 2026, ~7:43pm BST]: commit 7397a07f2f2684a8ef0bcd18e1f1e6a00679c5d8 exists, explicitly supersedes commit 91c2ae6's wrong 'expected behavior' analysis. ROOT CAUSE: AdminSettings DO's installedFormatBlueprints stamp persisted across re-deploy even when KV/R2 bindings switched from legacy to fresh v2; same bundle/manifest version caused skip at src/admin-settings.ts:101. #promoteBundledFormats ran outside stamp check, yielding .adminConfig + 3 enabled format records, but metadata absent in v2 KV; listFormatOffers filtered null metadata. TACTICAL FIX: manual seed v2 KV (3 metadata + .featured) + v2 R2 (format.document/1, format.spreadsheet/1, format.slides/1) verified by agent. STATUS: CODE FIX STILL REQUIRED — manual seed restores today but does NOT make profile/config-boundary changes safe. Required change: installation idempotency key must bind to the TARGET resource identity (e.g., manifest version + BLUEPRINTS namespace ID/R2 bucket ID) OR deployer executes an explicit post-provision seed step. This is a direct DEPLOYER_CONTRACT §7/§8 lesson: post-deploy verify must include required seeded-resource inventory, not HTTP health alone. New deterministic acceptance assertion: fresh-resource deployment → exactly 3 blueprint metadata records + .featured in target KV AND exactly 3 archives in target R2; test it before declaring a deployment green. FINAL USER CHECK: reload Workspace and ask/list blueprints — actual UI offers must be observed before status flips VERIFIED.
[Update Sep 3, 2026]: [Update Sep 3, 2026, ~20:10 BST — Mike first-party]: blueprints VERIFIED visible in Workspace UI after manual seed — format.document, format.spreadsheet, and format.slides all present. STATUS: tactical fix complete; PERMANENT FIX REQUIRED: resource-identity-aware installation idempotency key OR explicit post-provision seed step, plus deterministic acceptance test (exact KV/R2 seed inventory assertion). Directing docucleardev to implement permanent fix now before factory deploy.
[Update Sep 3, 2026]: [Update Sep 3, 2026, ~20:30 BST — VERIFIED via GitHub connector]: commit a09cc602987ad304540075940ad22f5ed2f9eac9 landed. PERMANENT FIX IMPLEMENTED: resource-identity-aware idempotency (env.BLUEPRINTS.id + env.BLUEPRINT_CONTENT.bucketName bound into install stamp). ACCEPTANCE TEST PASSED: 5 KV keys (3 metadata + .featured + .adminConfig) + 3 R2 objects (format.document/1, format.spreadsheet/1, format.slides/1) verified. Submodule fix on local branch fix/blueprint-install-resource-stamp (cloudflare-os commit 475c41b) — upstream PR needed to cloudflare/cloudflare-os. STATUS: blueprint issue CLOSED. Ready to proceed to factory deploy.
Tags: docuclear, work-item, docuclear-control, bootstrap, deployment, opencode, project:docuclear, duplicate-candidate, kind:episodic, volatility:state — Source: mcp — 2026-09-03 12:35:56 UTC