@hiveku-apps/sync 0.1.0 → 0.3.0

package/README.md

@@ -78,6 +78,92 @@ narrowed tool list. Available: `full`, `sales`, `marketing`, `helpdesk`,
 `pm`, `dev`. Change `HIVEKU_PROFILE` in `.env` and reload the MCP server
 in your editor to switch.
 
+## Codex (OpenAI) support
+
+By default `init` scaffolds a Claude Code folder (`.mcp.json` + `CLAUDE.md`). Add
+`--codex` to also write the Codex-native equivalents so the same folder works
+from the **Codex CLI / IDE extension / ChatGPT desktop**:
+
+```bash
+# Scaffold with the Codex lane too:
+hiveku-sync init acme-corp --codex
+
+# Or retrofit an existing account folder (run after `pull` to include the
+# account's latest skills/commands):
+cd acme-corp && hiveku-sync codex
+```
+
+This writes, merge-safely (only Hiveku-managed regions are touched):
+
+- **`AGENTS.md`** — Codex's `CLAUDE.md` equivalent: a lean pointer to `CLAUDE.md`
+  plus the load-bearing rules (Codex caps the instruction chain at ~32 KiB).
+- **`.codex/config.toml`** — the same `core.hiveku.com/mcp` server via
+  `[mcp_servers.hiveku]`, git-ignored. Your `OLYMPUS_API_KEY` is **inlined** when
+  `.env` has it (self-contained, no env setup); otherwise it's read from the
+  `OLYMPUS_API_KEY` env var. Also wires `playwright` for visual checks.
+- **`.agents/skills/<name>/SKILL.md`** — the account's pulled `skills/` and
+  `commands/` mirrored as repo-scoped Codex skills (Codex prompts are global-only
+  and deprecated).
+
+Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
+the repo config without its first-run trust prompt). Codex ignores repo-level
+approval/sandbox config, so the safe-work rules ship as instructions in
+`AGENTS.md`, not enforced permissions.
+
+> **This vs. the plugin.** For a single account, you can instead install the
+> published [Hiveku Codex plugin](https://github.com/locus2012/hiveku-codex-plugin)
+> once (`codex plugin marketplace add locus2012/hiveku-codex-plugin`) and set
+> `HIVEKU_TOKEN`. `hiveku-sync --codex` is the self-contained, per-account route —
+> better for multi-account / CI / power-user setups, and it also brings the
+> account's own knowledge. Use one route per folder, not both.
+
+## Coder projects — pull, ship, deploy
+
+Beyond memory/rules/skills, `hiveku-sync` can drive a Hiveku **website project**
+end-to-end from the terminal — the same push/deploy loop the VS Code extension's
+Source Control gives you, but headless (Claude Code in a terminal, CI, a cron).
+
+```bash
+hiveku-sync projects                    # list the account's coder projects
+hiveku-sync pull-project <slug-or-id>   # → ./projects/<slug>/  (+ .hiveku/projects.json)
+
+cd projects/<slug>
+hiveku-sync pull-env                    # secrets → .env.local (git-ignored)
+# ...edit files, run the dev server...
+hiveku-sync status                      # diff local vs the deploy source
+hiveku-sync push                        # save changes to the deploy source
+hiveku-sync push --deploy development --wait   # ...then deploy and wait
+```
+
+**`push` writes the deploy source, lane-routed.** This is the important part.
+`deploy_site` builds from `builder_code_versions` (+ the S3/CDN asset store) —
+**not** a GitHub branch. So `push`:
+
+- routes **CDN-servable binary** (images/fonts/video under `public/<subdir>/`)
+  to `assets_upload` (S3 → CloudFront). A binary put in `builder_code_versions`
+  renders in the Fly preview but **vanishes on deploy** (the build excludes it) —
+  `push` never makes that mistake.
+- routes everything else (code, config, text-under-public) to
+  `project_files_bulk_save` in small, per-batch-verified batches (transport-safe
+  vs one giant call).
+- diffs correctly: code via a single `project_files_status` call (so
+  `only_remote` stays reliable — chunking it produces phantom deletions), assets
+  via `assets_list` (so unchanged images aren't re-uploaded every push).
+
+Flags: `--include-deletes` (remove code paths missing locally), `--no-assets` /
+`--assets-all`, `--commit "msg"` (also record a Hiveku-native `main` commit),
+`--deploy <env> [--wait]`, `--dry-run`.
+
+```bash
+hiveku-sync deploy <development|staging|production> [<slug>] [--wait]
+hiveku-sync pull-env [<slug>] [--target development|staging|production]
+hiveku-sync commit -m "msg"   # legacy GitHub-branch commit (GitHub-connected projects only)
+```
+
+`pull-env` applies the same `_DEV` / `_PROD` / `_STAGING` suffix resolution the
+preview machine uses: for `development` it strips `_DEV` to the base key and
+skips `_PROD`/`_STAGING`; `--target production` does the inverse.
+
 ## Safety
 
 - **Manifest pin** — `.hiveku/manifest.json` records the API key preview.
@@ -91,7 +177,7 @@ in your editor to switch.
 
 ## How writes work
 
-`hiveku-sync` is pull-only. To persist changes back to Olympus, call the
-`memory_create` / `memory_update` / `memory_delete` MCP tools through
-Claude (or whichever LLM you've wired up). Then `hiveku-sync pull` to
-refresh the local copies.
+For **projects**, `hiveku-sync push` / `deploy` write straight back to Hiveku
+(see "Coder projects" above). For **memory/rules/skills**, `pull` is read-only —
+persist changes with the `memory_create` / `memory_update` / `memory_delete` MCP
+tools through Claude, then `hiveku-sync pull` to refresh the local copies.

package/bin/hiveku-sync.mjs

@@ -9,6 +9,7 @@
  */
 
 import { runInit } from '../src/init.mjs';
+import { runCodex } from '../src/init.mjs';
 import { runPull } from '../src/pull.mjs';
 import {
   runProjectsList,
@@ -16,20 +17,39 @@ import {
   runProjectStatus,
   runProjectPush,
 } from '../src/projects.mjs';
+import { runPush, runDeploy, runPullEnv } from '../src/push.mjs';
+import { pathToFileURL } from 'node:url';
 
-function parseFlags(argv) {
+export function parseFlags(argv) {
   const positional = [];
   const flags = {};
-  // Short flags that take a value (next arg is the value, not a new flag).
+  // Short flags that take the NEXT arg as their value.
   const VALUE_SHORT = new Set(['m']);
+  // Long flags that take the next arg as their value when not given with `=`.
+  const VALUE_LONG = new Set([
+    'message',
+    'commit',
+    'deploy',
+    'target',
+    'branch',
+    'profile',
+    'parent',
+  ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
-      if (eq === -1) {
-        flags[arg.slice(2)] = true;
-      } else {
+      if (eq !== -1) {
         flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        const key = arg.slice(2);
+        const nextIsValue = i + 1 < argv.length && !argv[i + 1].startsWith('-');
+        if (VALUE_LONG.has(key) && nextIsValue) {
+          flags[key] = argv[i + 1];
+          i += 1;
+        } else {
+          flags[key] = true;
+        }
       }
     } else if (arg.startsWith('-') && arg.length > 1) {
       const key = arg.slice(1);
@@ -50,27 +70,64 @@ const HELP = `hiveku-sync — sync a Hiveku account into a local Claude Code fol
 
 Memory/rules/skills:
   init <slug> [--profile=<name>]    Scaffold ./<slug>/ with .env, .mcp.json,
-                                    CLAUDE.md, and the memory/rules/skills tree.
+              [--codex] [--trust]   CLAUDE.md, and the memory/rules/skills tree.
+                                    --codex also writes the Codex lane (AGENTS.md
+                                    + .codex/config.toml + skills); --trust
+                                    pre-trusts the folder in ~/.codex/config.toml.
   pull [--profile=<name>]           Pull memory/rules/skills via MCP into the
                                     current account folder. Reads OLYMPUS_API_KEY
                                     and OLYMPUS_BASE_URL from ./.env.
+  codex [<folder>] [--trust]        Retrofit an existing account folder with the
+                                    Codex lane (AGENTS.md + .codex/config.toml +
+                                    mirror the account's skills/commands to
+                                    .agents/skills/). Run after 'pull' to include
+                                    the latest knowledge. Complements the published
+                                    Hiveku Codex plugin (single-account users can
+                                    instead run: codex plugin marketplace add
+                                    locus2012/hiveku-codex-plugin).
 
 Coder projects:
   projects                          List the account's coder projects.
   pull-project <slug-or-id>         Pull a project's source into ./projects/<slug>/.
                   [--branch=<name>] Records the project mapping in .hiveku/projects.json.
-  status [<slug>] [--json]          Diff local ./projects/<slug>/ vs Hiveku DB.
-                                    cd into the project folder to omit <slug>.
-  push  [<slug>] -m "<message>"     Save+commit changed files to the project's
-                  [--branch=<name>] GitHub branch via MCP (same path as the v3
-                  [--include-deletes] sidebar). Add --include-deletes to commit
-                  [--dry-run]       paths missing locally as deletions.
+  status [<slug>] [--json]          Diff local ./projects/<slug>/ vs the deploy source
+                                    (builder_code_versions). cd in to omit <slug>.
+
+Ship a project (the agent-native deploy loop):
+  push [<slug>]                     Save local changes to the DEPLOY SOURCE, lane-routed:
+       [--include-deletes]            images/fonts/video under public/<subdir>/ → the
+       [--no-assets] [--assets-all]   S3/CDN asset store; everything else → batched,
+       [--commit "<msg>"]             verified bulk_save. This is what deploy reads.
+       [--deploy <env>] [--wait]      --commit also records a Hiveku 'main' commit.
+       [--dry-run] [--branch=<name>]  --deploy <env> [--wait] deploys after the push.
+  deploy <env> [<slug>] [--wait]    Deploy to development | staging | production and
+                                    (with --wait) poll to a terminal status.
+  pull-env [<slug>]                 Write project secrets → .env.local (git-ignored),
+           [--target <env>]           with the same _DEV/_PROD/_STAGING resolution the
+                                      preview uses. --target staging|production for the
+                                      other tiers.
+  commit [<slug>] -m "<msg>"        GitHub-branch commit via project_commit (only for
+                  [--branch=<name>]   GitHub-connected projects; most sites use push).
+                  [--include-deletes]
 
   help                              Show this message.
 
 Profiles: full, sales, marketing, helpdesk, pm, dev
 `;
 
+function commitMessageFrom(flags) {
+  // --commit "msg" | --commit=msg | -m "msg" | --message "msg". A bare --commit
+  // (boolean true) means "commit with no message" → fall back to the default.
+  const c = typeof flags['commit'] === 'string' ? flags['commit'] : undefined;
+  const m = typeof flags['m'] === 'string' ? flags['m'] : undefined;
+  const msg = typeof flags['message'] === 'string' ? flags['message'] : undefined;
+  if (c) return c;
+  if (m) return m;
+  if (msg) return msg;
+  if (flags['commit'] === true) return 'hiveku-sync: push';
+  return undefined;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseFlags(rest);
@@ -87,6 +144,8 @@ async function main() {
         slug,
         parentDir: flags['parent'],
         profile: flags['profile'] || 'full',
+        codex: !!flags['codex'],
+        trust: !!flags['trust'],
       });
       console.log(`Initialized ${result.folder}`);
       console.log(`  profile: ${result.profile}`);
@@ -96,9 +155,33 @@ async function main() {
       if (result.workspaceAdded) {
         console.log(`  workspace: added entry to hiveku.code-workspace`);
       }
+      if (result.codex) {
+        console.log(`  codex: wrote AGENTS.md + .codex/config.toml (git-ignored)`);
+        console.log(
+          result.codex.inlinedKey
+            ? `    MCP auth: inlined your OLYMPUS_API_KEY`
+            : `    MCP auth: reads the OLYMPUS_API_KEY env var — after pasting your key into .env, run \`hiveku-sync codex\` to inline it, or \`export OLYMPUS_API_KEY=...\``,
+        );
+        if (result.codex.trust === 'added') console.log(`    trust: pre-trusted this folder in ~/.codex/config.toml`);
+      }
       console.log(`  then: cd ${result.folder} && hiveku-sync pull`);
       break;
     }
+    case 'codex': {
+      const result = await runCodex({ folder: positional[0], trust: !!flags['trust'] });
+      console.log(`Codex lane ready in ${result.folder} (profile=${result.profile})`);
+      console.log(`  AGENTS.md + .codex/config.toml written (git-ignored).`);
+      console.log(
+        result.inlinedKey
+          ? `  MCP auth: inlined OLYMPUS_API_KEY from .env.`
+          : `  MCP auth: reads the OLYMPUS_API_KEY env var (no key found in .env to inline) — set it, or paste it into .env and re-run.`,
+      );
+      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/command entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/.`);
+      if (result.trust === 'added') console.log(`  trust: pre-trusted this folder in ~/.codex/config.toml.`);
+      else if (result.trust === 'already') console.log(`  trust: folder already trusted.`);
+      console.log(`  verify: cd there, run \`codex mcp list\` (the hiveku row), then \`get_account_info\`.`);
+      break;
+    }
     case 'pull': {
       const summary = await runPull({ profile: flags['profile'] });
       console.log(`Pulled ${summary.total} entries (profile=${summary.profile}, base=${summary.baseUrl}):`);
@@ -144,16 +227,55 @@ async function main() {
       break;
     }
     case 'push': {
-      // Positional layout: `push [<slug>]`. -m / --message is required.
-      const slug = positional[0];
-      const message = flags['m'] || flags['message'];
-      if (!message) {
-        console.error('Error: push requires -m "<commit message>"\n');
+      const deployEnv = typeof flags['deploy'] === 'string' ? flags['deploy'] : undefined;
+      await runPush({
+        slug: positional[0],
+        profile: flags['profile'],
+        commit: commitMessageFrom(flags),
+        deploy: deployEnv,
+        wait: !!flags['wait'],
+        includeDeletes: !!flags['include-deletes'],
+        noAssets: !!flags['no-assets'],
+        assetsAll: !!flags['assets-all'],
+        dryRun: !!flags['dry-run'],
+        branch: flags['branch'],
+      });
+      break;
+    }
+    case 'deploy': {
+      // `deploy <env> [<slug>]` — env is the first positional.
+      const environment = positional[0];
+      if (!environment) {
+        console.error('Error: deploy requires an environment: development | staging | production\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      await runDeploy({
+        environment,
+        slugOrId: positional[1],
+        wait: !!flags['wait'],
+        profile: flags['profile'],
+      });
+      break;
+    }
+    case 'pull-env': {
+      await runPullEnv({
+        slug: positional[0],
+        profile: flags['profile'],
+        target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
+      });
+      break;
+    }
+    case 'commit': {
+      // The legacy GitHub-branch commit path (project_commit). Requires a repo.
+      const message = commitMessageFrom(flags);
+      if (!message || message === 'hiveku-sync: push') {
+        console.error('Error: commit requires -m "<commit message>"\n');
         console.error(HELP);
         process.exit(1);
       }
       await runProjectPush({
-        slug,
+        slug: positional[0],
         message,
         branch: flags['branch'],
         profile: flags['profile'],
@@ -175,8 +297,14 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error(`hiveku-sync: ${err.message}`);
-  if (process.env.HIVEKU_SYNC_DEBUG) console.error(err.stack);
-  process.exit(1);
-});
+// Only run the CLI when invoked directly — importing this module (e.g. from
+// tests to reach parseFlags) must not execute main().
+const isEntrypoint =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntrypoint) {
+  main().catch((err) => {
+    console.error(`hiveku-sync: ${err.message}`);
+    if (process.env.HIVEKU_SYNC_DEBUG) console.error(err.stack);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.1.0",
-  "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
+  "version": "0.3.0",
+  "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",
   "author": "Hiveku",
   "homepage": "https://app.hiveku.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/locus2012/hiveku-sync.git"
+    "url": "git+https://github.com/locus2012/hiveku-sync.git"
   },
   "bugs": {
     "url": "https://github.com/locus2012/hiveku-sync/issues"
@@ -19,7 +19,8 @@
     "claude",
     "claude-code",
     "cli",
-    "olympus"
+    "olympus",
+    "codex"
   ],
   "bin": {
     "hiveku-sync": "bin/hiveku-sync.mjs"
@@ -36,6 +37,7 @@
     "access": "public"
   },
   "scripts": {
-    "start": "node bin/hiveku-sync.mjs"
+    "start": "node bin/hiveku-sync.mjs",
+    "test": "node --test 'test/*.test.mjs'"
   }
 }

package/src/codex.mjs

@@ -0,0 +1,242 @@
+/**
+ * Codex (OpenAI) support for hiveku-sync — the Codex-native equivalents of the
+ * Claude Code artifacts, so a Hiveku account folder works identically from the
+ * Codex CLI, the Codex IDE extension, and the ChatGPT desktop app (all three
+ * read the same files). Opt in with `--codex` on `init`, or run
+ * `hiveku-sync codex` in an existing folder.
+ *
+ * Writes, merge-safely (only our marked regions are rewritten; user content is
+ * preserved):
+ *   CLAUDE.md              → AGENTS.md  (lean pointer + load-bearing rules; Codex
+ *                            concatenates AGENTS.md with a ~32KiB cap, so the
+ *                            full guide stays in CLAUDE.md and AGENTS.md says to
+ *                            read it)
+ *   .mcp.json              → .codex/config.toml [mcp_servers.*] (the SAME
+ *                            core.hiveku.com/mcp server + the SAME OLYMPUS_API_KEY;
+ *                            inlined when we can resolve the key, else read from
+ *                            the OLYMPUS_API_KEY env var). git-ignored.
+ *   skill/command knowledge → .agents/skills/<name>/SKILL.md (repo-scoped; Codex
+ *                            prompts are global-only + deprecated)
+ *   permissions            → NO per-repo equivalent (Codex ignores approval/
+ *                            sandbox keys in repo config) — stated in AGENTS.md.
+ *
+ * This complements the published Hiveku Codex plugin
+ * (github.com/locus2012/hiveku-codex-plugin): the plugin ships the generic
+ * `hiveku` MCP server + doctrine skills for single-account users who install it
+ * once and set HIVEKU_TOKEN; this writes a SELF-CONTAINED per-account folder
+ * (its own MCP config + that account's own knowledge) for multi-account / CI /
+ * power-user setups. Use one route or the other per folder, not both.
+ */
+
+import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+
+import { loadDotenv } from './util.mjs';
+
+const AGENTS_BEGIN = '<!-- hiveku:begin -->';
+const AGENTS_END = '<!-- hiveku:end -->';
+const TOML_BEGIN = '# hiveku:begin (managed by hiveku-sync — do not edit inside)';
+const TOML_END = '# hiveku:end';
+const SKILL_STAMP = '<!-- generated-by: hiveku-sync (mirrored from account knowledge) -->';
+
+/** Replace (or append) the marked region inside existing content. */
+function upsertMarkedRegion(existing, begin, end, region) {
+  const b = existing.indexOf(begin);
+  const e = existing.indexOf(end);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + region + existing.slice(e + end.length);
+  }
+  const sep = existing.length && !existing.endsWith('\n\n') ? (existing.endsWith('\n') ? '\n' : '\n\n') : '';
+  return existing + sep + region + '\n';
+}
+
+/** AGENTS.md — lean on purpose (Codex caps the instruction chain at ~32KiB). */
+function agentsMdRegion({ slug }) {
+  return `${AGENTS_BEGIN}
+# Hiveku — ${slug}
+
+This folder is ONE Hiveku account (${slug}). Its MCP server \`hiveku\` (configured in
+\`.codex/config.toml\`) carries this account's API key — never operate a different account from here.
+
+**FIRST ACTION every session: read \`CLAUDE.md\` in this folder.** It is the full operating guide
+(written for Claude Code, applies to you identically): account tools, department data, project
+push/deploy flows, and the work-tracking rules. Ignore only its Claude-specific file paths
+(\`.claude/*\`) — your equivalents are \`.agents/skills/*\` (the account's mirrored skills/commands,
+invoked by name) and this file.
+
+Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
+- **Verify identity before ANY write:** \`get_account_info\` must return THIS account.
+- **You are NOT the only writer.** Others push to these same projects while you work. Check what is
+  current BEFORE you start (\`project_version_log\`) and AGAIN before you push (\`project_files_status\`
+  — \`changed\` = they edited it, \`only_remote\` = they added files you lack). Before any tree-replace
+  (\`delete_missing: true\`), \`dry_run\` first and READ the would-delete list — a file you did not send
+  may be someone else's NEW work. Never blind-overwrite.
+- **Keep ALL scratch work in \`.hiveku/tmp/\`** — never \`/tmp\` (shared across accounts), your home
+  dir, or the repo root.
+- **Never ingest local agent config into a project push.** \`.codex/config.toml\`, \`.mcp.json\`, and
+  \`.env*\` carry this account's key/secrets — exclude them from every tar/bulk-save. Secrets belong in
+  \`project_secrets_*\`, never in project code. Never read or print \`.env.local\`.
+- **PM tasks are required** — create one when you start, comment as you go, complete it when done,
+  attributed to the authenticated user (\`crm_list_users\`).
+- **Every completed task ends with an "Owner update"** — 2–4 calm, plain-language sentences a busy owner
+  can skim: benefit first, no alarm vocabulary, accurate.
+- Video generation is paid + capped — \`marketing_generate_video\` with \`dry_run: true\` first.
+
+Discover tools with \`hiveku_docs_search\` / \`hiveku_docs_get\` and \`hiveku_playbooks_list\` /
+\`hiveku_playbook_get\`. Codex ignores repo-level approval/sandbox config, so the rules above are
+instructions, not enforced permissions — follow them.
+${AGENTS_END}`;
+}
+
+/** The [mcp_servers.*] region for <folder>/.codex/config.toml. */
+function codexTomlRegion({ baseUrl, profile, apiKey }) {
+  const base = baseUrl.replace(/\/+$/, '');
+  const url = profile === 'full' ? `${base}/mcp` : `${base}/mcp?profile=${encodeURIComponent(profile)}`;
+  // Prefer an inlined key (self-contained, no env setup needed; the file is
+  // git-ignored). Fall back to the OLYMPUS_API_KEY env var when we can't
+  // resolve a real key at scaffold time (e.g. `init` before the user pastes it).
+  const auth = apiKey
+    ? `http_headers = { "Authorization" = "Bearer ${apiKey}" }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"`;
+  return `${TOML_BEGIN}
+[mcp_servers.hiveku]
+url = "${url}"
+${auth}
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest"]
+${TOML_END}`;
+}
+
+/** Add lines to .gitignore when missing (non-destructive). */
+async function appendGitignoreLines(folder, lines) {
+  const giPath = join(folder, '.gitignore');
+  let gi = '';
+  try {
+    gi = await readFile(giPath, 'utf8');
+  } catch {
+    /* new file */
+  }
+  const have = new Set(gi.split('\n').map((l) => l.trim()));
+  const missing = lines.filter((l) => !have.has(l));
+  if (missing.length === 0) return;
+  const sep = gi.length && !gi.endsWith('\n') ? '\n' : '';
+  await writeFile(giPath, gi + sep + missing.join('\n') + '\n', 'utf8');
+}
+
+/**
+ * Mirror the account's pulled skill + command knowledge into repo-scoped Codex
+ * skills at .agents/skills/<name>/SKILL.md. Reads the folders `hiveku-sync pull`
+ * writes (skills/, commands/). Idempotent: a skill dir without our stamp is
+ * left alone (user-authored). Returns the count written.
+ */
+export async function mirrorKnowledgeToSkills(folder) {
+  let written = 0;
+  for (const srcDir of ['skills', 'commands']) {
+    const root = join(folder, srcDir);
+    if (!existsSync(root)) continue;
+    // pull writes <type>/<department>/<slug>.md — walk one level of subdirs + top-level files.
+    const files = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        for (const f of await readdir(join(root, entry.name))) {
+          if (f.endsWith('.md')) files.push(join(root, entry.name, f));
+        }
+      } else if (entry.name.endsWith('.md')) {
+        files.push(join(root, entry.name));
+      }
+    }
+    for (const filePath of files) {
+      const src = await readFile(filePath, 'utf8');
+      const base = filePath.split('/').pop().replace(/\.md$/, '');
+      const name = `hiveku-${srcDir === 'commands' ? 'cmd' : 'skill'}-${base}`.slice(0, 100);
+      let description = `Hiveku ${srcDir === 'commands' ? 'command' : 'skill'}: ${base}`;
+      let body = src;
+      const fm = src.match(/^---\n([\s\S]*?)\n---\n?/);
+      if (fm) {
+        const d = fm[1].match(/^description:\s*(.+)$/m);
+        if (d) description = d[1].trim().replace(/^["']|["']$/g, '');
+        body = src.slice(fm[0].length);
+      }
+      body = body.replace(/\$ARGUMENTS/g, '(the arguments the user gave after the skill name)');
+      const skillDir = join(folder, '.agents', 'skills', name);
+      const skillPath = join(skillDir, 'SKILL.md');
+      try {
+        const existing = await readFile(skillPath, 'utf8');
+        if (!existing.includes(SKILL_STAMP)) continue; // user-authored — never clobber
+      } catch {
+        /* new */
+      }
+      await mkdir(skillDir, { recursive: true });
+      const skill = `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\n${SKILL_STAMP}\n\n${body.trimStart()}`;
+      await writeFile(skillPath, skill, 'utf8');
+      written += 1;
+    }
+  }
+  return written;
+}
+
+/**
+ * Write/refresh the Codex scaffold for one account folder: AGENTS.md +
+ * .codex/config.toml (git-ignored) + mirror the account's knowledge to skills.
+ * Resolves OLYMPUS_API_KEY from the folder's .env / process env to inline the
+ * MCP auth when possible.
+ */
+export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
+  const dotenv = await loadDotenv(join(folder, '.env'));
+  const apiKey =
+    process.env.OLYMPUS_API_KEY ||
+    (dotenv.OLYMPUS_API_KEY && dotenv.OLYMPUS_API_KEY !== 'olp_replace_me' ? dotenv.OLYMPUS_API_KEY : '');
+
+  // AGENTS.md (marker-managed)
+  const agentsPath = join(folder, 'AGENTS.md');
+  let agents = '';
+  try {
+    agents = await readFile(agentsPath, 'utf8');
+  } catch {
+    /* new */
+  }
+  await writeFile(agentsPath, upsertMarkedRegion(agents, AGENTS_BEGIN, AGENTS_END, agentsMdRegion({ slug })), 'utf8');
+
+  // .codex/config.toml (marker-managed region; rest of user's config untouched)
+  const tomlPath = join(folder, '.codex', 'config.toml');
+  let toml = '';
+  try {
+    toml = await readFile(tomlPath, 'utf8');
+  } catch {
+    /* new */
+  }
+  await mkdir(dirname(tomlPath), { recursive: true });
+  await writeFile(tomlPath, upsertMarkedRegion(toml, TOML_BEGIN, TOML_END, codexTomlRegion({ baseUrl, profile, apiKey })), 'utf8');
+
+  await appendGitignoreLines(folder, ['.codex/config.toml']);
+
+  const skills = await mirrorKnowledgeToSkills(folder);
+  return { inlinedKey: !!apiKey, skillsMirrored: skills };
+}
+
+/**
+ * Pre-trust a folder in the USER-GLOBAL ~/.codex/config.toml so its repo-level
+ * .codex/config.toml (which carries the MCP server + key) loads without Codex's
+ * first-run trust prompt. Crosses a security boundary — the caller must have
+ * explicit user intent (the `--trust` flag).
+ */
+export async function preTrustFolder(folder) {
+  const cfgPath = join(homedir(), '.codex', 'config.toml');
+  let cfg = '';
+  try {
+    cfg = await readFile(cfgPath, 'utf8');
+  } catch {
+    /* none yet */
+  }
+  const abs = resolve(folder);
+  const header = `[projects."${abs}"]`;
+  if (cfg.includes(header)) return 'already';
+  await mkdir(dirname(cfgPath), { recursive: true });
+  const sep = cfg.length && !cfg.endsWith('\n') ? '\n' : '';
+  await writeFile(cfgPath, `${cfg}${sep}\n${header}\ntrust_level = "trusted"\n`, 'utf8');
+  return 'added';
+}