@hiveku-apps/sync 0.3.2 → 0.3.5

package/README.md

@@ -8,6 +8,8 @@ Local sync CLI for a Hiveku account. Pairs with the Hiveku MCP server at
 2. **`hiveku-sync pull`** — fetch the account's memory/rules/skills via the
    `memory_list` MCP tool and write each entry as a Markdown file with
    YAML frontmatter (name, type, domain, department, version, updated_at).
+   It also writes the account memory (see "Account memory" below) to
+   `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only.
 
 The goal: open one folder per Hiveku tenant in VS Code with Claude Code,
 and the local `.md` files become the source-of-truth Claude reads. Tools
@@ -182,3 +184,25 @@ 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.
+
+## Account memory
+
+The account memory is the business facts every Hiveku department agent reads.
+Owners and admins edit it on the Hiveku dashboard, under Account memory
+(`https://app.hiveku.com/<account id>/dashboard/memory`); no tool sets it.
+
+`pull` reads it with `account_memory_get` and writes one file,
+`hiveku-data/account/ACCOUNT_MEMORY.md`, the same file, byte for byte, that the
+Hiveku plugin and the VS Code extension write. The file is read-only on disk and
+starts with a note saying where it is edited, with the link (the unscoped
+`https://app.hiveku.com/dashboard/memory` when the account id cannot be read),
+and that it is internal to the team. The owners' text comes first, then the suggestions
+agents and team members made that an owner has not reviewed yet, each with who
+suggested it and when. The two account-memory rows (`account` and
+`account-suggestions`) are never written under `memory/`, even when an older
+server still lists them.
+
+Nothing uploads this file: `push`, `commit` and `status` leave any
+`hiveku-data/account/` folder out, and the next `pull` replaces it. To add a
+fact, suggest it with the `account_memory_append` tool; an owner keeps or
+removes it on the dashboard.

package/bin/hiveku-sync.mjs

@@ -189,6 +189,13 @@ async function main() {
       for (const [type, count] of Object.entries(summary.by_type)) {
         console.log(`  ${type}: ${count}`);
       }
+      if (summary.account_memory) {
+        const am = summary.account_memory;
+        console.log(
+          `  account memory: ${am.file} (read-only; ${am.version > 0 ? `version ${am.version}` : 'not written yet'}, ` +
+            `${am.suggestions} suggestion${am.suggestions === 1 ? '' : 's'} waiting). Owners edit it on the dashboard.`,
+        );
+      }
       if (summary.removed_remotely.length > 0) {
         console.log('\nNote: these files were present in the last sync but are no longer in Olympus:');
         for (const f of summary.removed_remotely) console.log(`  ${f}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "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",

package/src/account-memory.mjs

@@ -0,0 +1,240 @@
+/**
+ * The account memory, pulled read-only.
+ *
+ * The account memory is the business facts every Hiveku department agent reads.
+ * It lives in two rows of account_ai_memory, and neither is a department:
+ *
+ *   domain `account`              the owner's document (owners and admins edit
+ *                                 it on the dashboard, nowhere else);
+ *   domain `account-suggestions`  one-line suggestions from agents, MCP clients
+ *                                 and team members, waiting for an owner's
+ *                                 Keep or Remove (JSON Lines).
+ *
+ * Neither row may land in the memory/ tree as if it were a department's
+ * document: `account-suggestions` would be raw JSON Lines, and a local edit to
+ * either would look like something `memory_update` could write back, which the
+ * server refuses. So `hiveku-sync pull` classifies both domains explicitly and
+ * writes one read-only file instead, in the same place the Hiveku plugin does:
+ *
+ *   hiveku-data/account/ACCOUNT_MEMORY.md
+ *
+ * from `account_memory_get`. Nothing in hiveku-sync ever uploads that file:
+ * there is no tool that sets the account memory, and `push` leaves the folder
+ * out (see isAccountMemoryPath).
+ */
+
+import { chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import { writeFileAtomic } from './util.mjs';
+
+export const ACCOUNT_MEMORY_DOMAIN = 'account';
+export const ACCOUNT_SUGGESTIONS_DOMAIN = 'account-suggestions';
+export const ACCOUNT_MEMORY_DOMAINS = new Set([ACCOUNT_MEMORY_DOMAIN, ACCOUNT_SUGGESTIONS_DOMAIN]);
+
+/** Folder and file, relative to the account folder (same layout as the plugin). */
+export const ACCOUNT_DATA_DIR = 'hiveku-data/account';
+export const ACCOUNT_MEMORY_FILE = `${ACCOUNT_DATA_DIR}/ACCOUNT_MEMORY.md`;
+
+export const APP_URL = 'https://app.hiveku.com';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isAccountMemoryDomain(domain) {
+  return typeof domain === 'string' && ACCOUNT_MEMORY_DOMAINS.has(domain.trim());
+}
+
+/**
+ * Where a memory_list row belongs. The two account domains are named
+ * explicitly, before any folder or department tag is looked at: they carry no
+ * department tag, so a generic rule would file them under memory/ (or, in a
+ * by-department layout, invent an "account" department).
+ *
+ *   { kind: 'account' }              the owner document (written from account_memory_get)
+ *   { kind: 'account-suggestions' }  the suggestions row (listed under the document)
+ *   { kind: 'knowledge', folder }    everything else, in its type's folder
+ */
+export function classifyMemoryEntry(entry, folder) {
+  const domain = typeof entry?.domain === 'string' ? entry.domain.trim() : '';
+  if (domain === ACCOUNT_MEMORY_DOMAIN) return { kind: 'account' };
+  if (domain === ACCOUNT_SUGGESTIONS_DOMAIN) return { kind: 'account-suggestions' };
+  return { kind: 'knowledge', folder };
+}
+
+/**
+ * True for a path (relative, forward or back slashes) inside the pulled
+ * account-memory folder, wherever that folder sits. `push` drops these paths,
+ * so the read-only copy can never be uploaded as site code.
+ */
+export function isAccountMemoryPath(relPath) {
+  const p = String(relPath || '').replace(/\\/g, '/').replace(/^\.?\//, '');
+  return p === ACCOUNT_DATA_DIR || p.startsWith(`${ACCOUNT_DATA_DIR}/`) || p.includes(`/${ACCOUNT_DATA_DIR}/`);
+}
+
+export const ACCOUNT_MEMORY_TOOL = 'account_memory_get';
+
+/** The builder's dashboard page (src/app/dashboard/memory, scoped mirror under /[accountId]). */
+const DASHBOARD_PATH = 'dashboard/memory';
+
+/*
+ * ONE FILE, THREE WRITERS. The Claude Code plugin (lib/account-memory.mjs),
+ * the VS Code extension (src/accountMemory.ts) and hiveku-sync all write
+ * hiveku-data/account/ACCOUNT_MEMORY.md, and the plugin reads its front matter
+ * back (`fetched_at`, for `pull --list` and `--stale`). So everything from here
+ * to writeReadOnly is a port of the plugin's normalizeAccountMemory,
+ * accountMemoryDashboardUrl and renderAccountMemoryFile, and
+ * test/account-memory.test.mjs compares the two byte for byte whenever a plugin
+ * checkout sits beside this repo. Change them together.
+ */
+
+/**
+ * The page where owners and admins edit it. Account-scoped when the account id
+ * is a real UUID (the scoped route opens on the right account for a person in
+ * several); the unscoped page otherwise, never a half-built URL.
+ */
+export function accountMemoryDashboardUrl(accountId, appUrl = APP_URL) {
+  const base = String(appUrl || APP_URL).replace(/\/+$/, '');
+  return typeof accountId === 'string' && UUID_RE.test(accountId)
+    ? `${base}/${accountId.toLowerCase()}/${DASHBOARD_PATH}`
+    : `${base}/${DASHBOARD_PATH}`;
+}
+
+/**
+ * The tool result, checked. account_memory_get returns the builder's
+ * `{ data: { content, version, updated_at, bytes, suggestions, suggestions_version,
+ * injected, truncated } }`. Anything else is an error, not an empty memory:
+ * writing "nothing written yet" over a real document because the shape moved
+ * would be a lie on disk.
+ */
+export function normalizeAccountMemory(payload) {
+  const inner = payload && typeof payload === 'object' && !Array.isArray(payload) && 'data' in payload ? payload.data : payload;
+  if (!inner || typeof inner !== 'object' || Array.isArray(inner)) {
+    throw new Error(`${ACCOUNT_MEMORY_TOOL} returned an unexpected shape (no object)`);
+  }
+  if (typeof inner.content !== 'string' || !Number.isFinite(Number(inner.version))) {
+    throw new Error(`${ACCOUNT_MEMORY_TOOL} returned an unexpected shape (no content or version)`);
+  }
+  const suggestions = Array.isArray(inner.suggestions) ? inner.suggestions : [];
+  return {
+    content: inner.content,
+    version: Number(inner.version),
+    updated_at: typeof inner.updated_at === 'string' ? inner.updated_at : null,
+    suggestions: suggestions
+      .filter((s) => s && typeof s === 'object' && typeof s.text === 'string' && s.text.trim())
+      .map((s) => ({
+        id: typeof s.id === 'string' ? s.id : '',
+        at: typeof s.at === 'string' ? s.at : '',
+        source: typeof s.source === 'string' && s.source.trim() ? s.source : 'Unknown',
+        text: s.text,
+      })),
+    suggestions_version: Number.isFinite(Number(inner.suggestions_version)) ? Number(inner.suggestions_version) : 0,
+    truncated: inner.truncated === true,
+  };
+}
+
+/** "2026-09-23 14:02 UTC", or the raw value when it is not a date. */
+function readableTime(value) {
+  if (!value) return 'unknown time';
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  return `${d.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+/** One line, no line breaks: a suggestion is one line on the server too. */
+function oneLine(value) {
+  return String(value).replace(/[\r\n\u2028\u2029]+/g, ' ').trim();
+}
+
+function yamlString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * The file text. Plain language: the person reading it may be the owner.
+ * Held suggestions (from the agents that talk to customers, and onboarding)
+ * are never in the tool's answer, so they are never here either.
+ */
+export function renderAccountMemoryFile({ memory, accountId, fetchedAt, appUrl = APP_URL }) {
+  const editUrl = accountMemoryDashboardUrl(accountId, appUrl);
+  const fm = [
+    '---',
+    `read_only: true`,
+    `source_tool: ${ACCOUNT_MEMORY_TOOL}`,
+    `version: ${memory.version}`,
+    ...(memory.updated_at ? [`updated_at: ${yamlString(memory.updated_at)}`] : []),
+    `suggestions: ${memory.suggestions.length}`,
+    `suggestions_version: ${memory.suggestions_version}`,
+    `fetched_at: ${yamlString(fetchedAt)}`,
+    `edit_url: ${yamlString(editUrl)}`,
+    '---',
+    '',
+  ];
+  const lines = [
+    '# Account memory',
+    '',
+    '> This is a read-only copy of the account memory, the facts about the business that every',
+    '> Hiveku department agent reads. Owners and admins edit it on the Hiveku dashboard:',
+    `> ${editUrl}`,
+    '>',
+    '> Changes made to this file are not saved to Hiveku. The next pull replaces this file, and',
+    '> nothing uploads it. To add a fact, suggest it with account_memory_append (an owner or admin',
+    '> reviews it on the dashboard), or ask an owner or admin to change the document there.',
+    '> It is internal to the team: do not quote it to customers.',
+    '',
+  ];
+  if (memory.version > 0 && memory.content.trim()) {
+    lines.push(`Version ${memory.version}, last changed ${readableTime(memory.updated_at)}.`);
+    if (memory.truncated) {
+      lines.push(
+        'Agents see a shortened version: with the suggestions, it is longer than the 8,000 characters they read.',
+      );
+    }
+    lines.push('', '---', '', memory.content.replace(/\s+$/, ''), '', '---', '');
+  } else {
+    lines.push('Nothing has been written yet. An owner or admin can start it on the dashboard.', '');
+  }
+
+  lines.push('# Suggestions from agents, not reviewed yet', '');
+  if (memory.suggestions.length) {
+    lines.push(
+      'These lines are not part of the account memory until an owner or admin keeps them on the dashboard.',
+      '',
+    );
+    for (const s of memory.suggestions) {
+      lines.push(`- ${oneLine(s.text)} (suggested by ${oneLine(s.source)}, ${readableTime(s.at)})`);
+    }
+  } else {
+    lines.push('None waiting.');
+  }
+  lines.push('');
+  return fm.join('\n') + lines.join('\n');
+}
+
+/** Write the file read-only (0444), replacing any earlier read-only copy. */
+export async function writeReadOnly(path, contents) {
+  if (existsSync(path)) {
+    // A 0444 file can be renamed over on POSIX, but not on Windows; open it up
+    // for the replace, then lock it again.
+    await chmod(path, 0o644).catch(() => {});
+  }
+  await writeFileAtomic(path, contents);
+  await chmod(path, 0o444);
+}
+
+/**
+ * The account id for the dashboard link, from get_account_info. The key is
+ * pinned to one account, so the first row is it. Any failure (a narrowed
+ * profile without the tool, an older server) gives null, and the link falls
+ * back to the unscoped dashboard page.
+ */
+export async function resolveAccountId(client) {
+  try {
+    const result = await client.callToolJson('get_account_info', {});
+    const data = result?.data ?? result;
+    const row = Array.isArray(data) ? data[0] : data;
+    const id = typeof row?.id === 'string' ? row.id.trim() : '';
+    return UUID_RE.test(id) ? id : null;
+  } catch {
+    return null;
+  }
+}

package/src/codex.mjs

@@ -68,6 +68,11 @@ 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.
+- **Context and memory.** Call \`account_context_get({ domain })\` first, before any copy, plan or analysis.
+  The account memory is read-only to you: owners edit it on the Hiveku dashboard, the local copy is
+  \`hiveku-data/account/ACCOUNT_MEMORY.md\` (never edit or upload it); suggest one line with \`account_memory_append\`.
+  Department memory is ONE document per department: read it (\`memory_list({ domain })\`), merge, then send the
+  whole document with \`memory_update({ memory_id, content })\`. Never create-then-overwrite on a 409.
 - **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
@@ -82,6 +87,10 @@ Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
   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.
+- **Hiveku itself in your way?** A Hiveku tool still failing after one sensible retry → \`hiveku_report_issue\`;
+  a capability no tool offers (search \`hiveku_docs_search\` first) → \`hiveku_request_feature\`. No secrets or personal data.
+- **Tell the user only if it changes what they get:** one or two calm sentences — flagged to the Hiveku team (give the
+  ref), the team is quick to fix these, you'll let them know when it's sorted. No error codes, blame or promised times.
 - 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\` /
@@ -97,9 +106,17 @@ function codexTomlRegion({ baseUrl, profile, apiKey }) {
   // 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).
+  //
+  // http_headers is Codex's map of static HTTP headers for a streamable HTTP
+  // MCP server (Codex config reference, "mcp_servers.<id>.http_headers"; the
+  // docs' example is `http_headers = { "X-Figma-Region" = "us-east-1" }`, next
+  // to bearer_token_env_var). TOML allows the key once per table, so the
+  // client label rides in the same inline table as an inlined key.
+  // X-Hiveku-Client: codex is what the MCP server's memory log shows as
+  // "via Codex"; it is a label, never authentication.
   const auth = apiKey
-    ? `http_headers = { "Authorization" = "Bearer ${apiKey}" }`
-    : `bearer_token_env_var = "OLYMPUS_API_KEY"`;
+    ? `http_headers = { "Authorization" = "Bearer ${apiKey}", "X-Hiveku-Client" = "codex" }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = "codex" }`;
   // default_tools_approval_mode = "approve": this folder exists so the agent
   // can operate the account — per-call approval prompts would also auto-cancel
   // every tool call in headless `codex exec` (CI/cron), this lane's core use.

package/src/init.mjs

@@ -64,6 +64,9 @@ exposes the **${profile}** profile of Olympus tools.
 - \`rules/\` — synced agent rules
 - \`skills/\` — synced agent skills
 - \`commands/\`, \`agents/\`, \`identity/\` — other memory types
+- \`hiveku-data/account/ACCOUNT_MEMORY.md\` — the account memory (the business
+  facts every department agent reads), **read-only**: owners and admins edit it on
+  the Hiveku dashboard under Account memory, and nothing uploads this file
 - \`projects/<slug>/\` — coder project source pulled via \`hiveku-sync pull-project\`
 - \`.hiveku/manifest.json\` — memory last-sync record
 - \`.hiveku/projects.json\` — project ID ↔ folder mapping
@@ -81,6 +84,16 @@ changes (new skill, updated rule, etc.), call the corresponding MCP tool:
   commands, agents, identity entries
 - \`memory_delete\` — to remove an entry
 
+\`memory_update\` replaces the whole entry. Each department's memory is ONE
+document, so read the current one with \`memory_list({ domain })\`, merge your
+change into its full text, and send the whole document. Use \`memory_create\`
+only when none exists; a 409 means one does, so read and merge, never overwrite.
+
+The account memory is the exception: no tool sets it. Read it with
+\`account_memory_get\`, suggest one line with \`account_memory_append\` (an owner
+keeps or removes it), and tell the user that owners and admins edit it on the
+Hiveku dashboard under Account memory.
+
 Then run \`hiveku-sync pull\` to refresh the local copies.
 
 ## Coder projects (pull / status / push)
@@ -112,6 +125,14 @@ You can also ask Claude in this workspace to:
 Claude has the \`project_files_list\`, \`project_file_get\`, \`project_files_status\`,
 and \`project_commit\` MCP tools available under the **${profile}** profile.
 
+## When Hiveku itself gets in your way
+
+- A Hiveku tool still failing after one sensible retry → \`hiveku_report_issue\`; a capability
+  no tool offers (search \`hiveku_docs_search\` first) → \`hiveku_request_feature\`. No secrets or personal data.
+- Tell the user only if it changes what they get: one or two calm sentences — flagged to the Hiveku
+  team (give the ref), the team is quick to fix these, you'll let them know when it's sorted. No
+  error codes, blame or promised times.
+
 ## Tenant scope
 
 The API key in \`.env\` is **pinned to one Hiveku account**. You cannot switch

package/src/projects.mjs

@@ -19,6 +19,7 @@ import {
   writeFileAtomic,
   readJson,
 } from './util.mjs';
+import { isAccountMemoryPath } from './account-memory.mjs';
 // NOTE: push.mjs imports helpers from this module; the cycle is safe because
 // both sides reference the imports only inside functions (never at module eval).
 import { computePushPlan } from './push.mjs';
@@ -47,8 +48,37 @@ const RUN_HINTS = {
   'python-lambda': 'python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt',
   expo: 'npm install && npx expo start',
   static: 'npx serve .',
+  // The server's name for a static site is `static-html` (site_create's enum);
+  // `static` above is kept for rows created before that name settled.
+  'static-html': 'npx serve .',
+  external:
+    '# External site: there is no code to run. Manage it from the Hiveku dashboard (Webflow sites: /dashboard/<project id>/webflow) or the webflow_* MCP tools.',
 };
 
+/**
+ * Project types with no code tree to mirror. Mirrors the builder's
+ * NO_LOCAL_CODE_TYPES minus python-lambda, which hiveku-sync still pulls and
+ * ships with the run hint above; folding it in is a separate decision.
+ */
+const EXTERNAL_TYPES = new Set(['external']);
+
+/**
+ * Refuse an external project (a site hosted on Webflow, WordPress or any other
+ * host that Hiveku only tracks) before any file, VCS or deploy call. Accepts a
+ * project_get/sites_list row (`id`) or a projects.json manifest row
+ * (`project_id`); both carry `project_type`, the former `external_platform`.
+ */
+export function refuseExternal(project) {
+  if (!project || !EXTERNAL_TYPES.has(String(project.project_type || '').toLowerCase())) return;
+  const id = project.id || project.project_id;
+  const platform = project.external_platform ? `, platform=${project.external_platform}` : '';
+  throw new Error(
+    `"${project.name || id}" is an external site (project_type=external${platform}). ` +
+      `hiveku-sync mirrors code projects only; edit this site in the Hiveku dashboard ` +
+      `(/dashboard/${id}/webflow for Webflow) or through the webflow_* MCP tools.`,
+  );
+}
+
 export function sha256(content) {
   return createHash('sha256').update(content).digest('hex');
 }
@@ -89,6 +119,12 @@ async function listAllRemoteFiles(client, projectId) {
   return all;
 }
 
+/**
+ * Every local file push, commit and status consider. The pulled account memory
+ * (hiveku-data/account/) is left out wherever it sits: it is a read-only copy
+ * that owners edit on the dashboard, and nothing may upload it, not even when
+ * an account folder and a project folder are the same folder.
+ */
 export async function walkLocalFiles(rootDir) {
   const out = [];
   async function recurse(dir) {
@@ -102,6 +138,7 @@ export async function walkLocalFiles(rootDir) {
       if (entry.name.startsWith('.')) continue;
       if (IGNORE_DIRS.has(entry.name)) continue;
       const full = join(dir, entry.name);
+      if (isAccountMemoryPath(relative(rootDir, full).split(sep).join('/'))) continue;
       if (entry.isDirectory()) {
         await recurse(full);
       } else if (entry.isFile()) {
@@ -124,10 +161,21 @@ async function buildLocalManifest(rootDir) {
   return manifest;
 }
 
-function runHintForProjectType(type) {
+export function runHintForProjectType(type) {
   return RUN_HINTS[type] || `# Unknown project_type "${type}". Inspect package.json/requirements.txt to find the dev command.`;
 }
 
+/**
+ * The MCP client and account folder an entry point works with. Tests inject
+ * `client` (a fake with callToolJson) and `baseDir`; the CLI passes neither and
+ * gets the .env-configured client with cwd as the account folder.
+ */
+async function resolveClient({ client, profile, baseDir } = {}) {
+  if (client) return { client, baseDir: baseDir || process.cwd() };
+  const resolved = await clientFromCwd({ profileOverride: profile });
+  return { client: resolved.client, baseDir: baseDir || resolved.baseDir };
+}
+
 export async function readProjectsManifest(baseDir) {
   const data = await readJson(join(baseDir, PROJECTS_MANIFEST));
   return data && typeof data === 'object' ? data : { projects: {} };
@@ -137,45 +185,202 @@ export async function writeProjectsManifest(baseDir, manifest) {
   await writeFileAtomic(join(baseDir, PROJECTS_MANIFEST), JSON.stringify(manifest, null, 2));
 }
 
-export async function resolveProject(client, slugOrId) {
-  // Accept either UUID (use directly) or slug (look up via list_projects).
-  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  if (UUID_RE.test(slugOrId)) {
-    const result = await client.callToolJson('get_project', { project_id: slugOrId });
-    return result?.data || result;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// sites_list and list_projects both cap `limit` at 100 server-side.
+const LIST_PAGE_LIMIT = 100;
+
+/**
+ * Two id spaces, two tool families (S2, confirmed live 2026-09-10):
+ *
+ *   website_projects  — the code this CLI pulls, pushes and deploys.
+ *                       Read with `project_get` (one) and `sites_list` (all).
+ *   pm_projects       — project-MANAGEMENT rows (tasks, owners, status), with
+ *                       project_type seo|ppc|marketing|website|... and their
+ *                       own ids. Read with `get_project` and `list_projects`.
+ *                       A PM row may point at a website project through
+ *                       `website_project_id` / `linked_site`.
+ *
+ * Until 0.3.3 resolveProject used the PM tools for both shapes: a website
+ * UUID got get_project's 404 back as the "project", and a slug got a PM row
+ * whose id then 404'd on every file call and whose project_type "website"
+ * stamped an "Unknown project_type" RUN.md. Every lookup below lands on a
+ * website_projects row, which carries the project_type and external_platform
+ * that refuseExternal reads.
+ */
+
+/** Does this error (thrown or returned) mean the row does not exist, as opposed to any other failure? */
+function isNotFoundText(text) {
+  return /"status"\s*:\s*404\b|\bproject not found\b|Olympus API returned 404\b/i.test(String(text || ''));
+}
+
+/**
+ * One lookup call that answers null for "no such row" instead of throwing.
+ * The MCP proxy flags an upstream 404 with isError, which callTool turns into
+ * a thrown Error carrying the status; older servers handed the error body
+ * back as a completed call with no `data`. Both read as null here. Anything
+ * else (network, auth, 500) still throws.
+ */
+async function lookupRow(client, toolName, args) {
+  let body;
+  try {
+    body = await client.callToolJson(toolName, args);
+  } catch (err) {
+    if (isNotFoundText(err?.message)) return null;
+    throw err;
+  }
+  const row = body && typeof body === 'object' && body.data && typeof body.data === 'object' && !Array.isArray(body.data)
+    ? body.data
+    : null;
+  if (row && row.id) return row;
+  if (body && typeof body === 'object' && body.error !== undefined) {
+    if (body.status === 404 || isNotFoundText(body.error)) return null;
+    throw new Error(`Tool ${toolName} failed: ${body.error}`);
+  }
+  return null;
+}
+
+/** Every row of a paginated list tool (sites_list, list_projects), walking `pagination.total_pages`. */
+async function listAllRows(client, toolName) {
+  const rows = [];
+  let page = 1;
+  while (true) {
+    const result = await client.callToolJson(toolName, { page, limit: LIST_PAGE_LIMIT });
+    const batch = Array.isArray(result?.data) ? result.data : [];
+    rows.push(...batch);
+    const totalPages = result?.pagination?.total_pages ?? 1;
+    if (page >= totalPages || batch.length === 0) break;
+    page += 1;
   }
-  const result = await client.callToolJson('list_projects', { search: slugOrId });
-  const list = result?.data || [];
-  const match =
-    list.find((p) => p.slug === slugOrId) ||
-    list.find((p) => p.name?.toLowerCase() === slugOrId.toLowerCase()) ||
-    list[0];
-  if (!match) {
-    throw new Error(`No project found matching "${slugOrId}"`);
+  return rows;
+}
+
+/** The website project a PM row points at, if any. */
+function linkedWebsiteId(pmRow) {
+  if (!pmRow) return null;
+  return pmRow.website_project_id || pmRow.linked_site?.id || null;
+}
+
+const PROJECTS_HINT = 'Run `hiveku-sync projects` to list the website projects on this account.';
+
+async function resolveProjectByUuid(client, projectId) {
+  const website = await lookupRow(client, 'project_get', { project_id: projectId });
+  if (website) return website;
+
+  // Not a website id. It may be the PM project that tracks one.
+  const pmRow = await lookupRow(client, 'get_project', { project_id: projectId });
+  const linkedId = linkedWebsiteId(pmRow);
+  if (linkedId) {
+    const linked = await lookupRow(client, 'project_get', { project_id: linkedId });
+    if (linked) return linked;
+    throw new Error(
+      `${projectId} is the PM project "${pmRow.name || projectId}" (pm_projects), which links website project ${linkedId}, ` +
+        `but project_get finds no website project with that id. ${PROJECTS_HINT}`,
+    );
+  }
+  if (pmRow) {
+    throw new Error(
+      `${projectId} is the PM project "${pmRow.name || projectId}" (pm_projects, the id space of get_project / list_projects) ` +
+        `and it links no website project. hiveku-sync pulls code from website projects ` +
+        `(website_projects, the id space of project_get / sites_list). ${PROJECTS_HINT}`,
+    );
+  }
+  throw new Error(
+    `No project with id ${projectId}: it is neither a website project (website_projects, the id space of ` +
+      `project_get / sites_list) nor a PM project (pm_projects, the id space of get_project / list_projects). ${PROJECTS_HINT}`,
+  );
+}
+
+/**
+ * Match a slug against website rows: exact subdomain, then exact name
+ * (case-insensitive), then the name slugified the way pull-project names the
+ * local folder, so the folder name under ./projects/ resolves too.
+ */
+function matchSiteRow(rows, slug) {
+  const lower = slug.toLowerCase();
+  const slugified = safeSlug(slug);
+  return (
+    rows.find((row) => String(row.subdomain || '').toLowerCase() === lower) ||
+    rows.find((row) => String(row.name || '').toLowerCase() === lower) ||
+    rows.find((row) => safeSlug(row.name) === slugified) ||
+    null
+  );
+}
+
+function matchPmRow(rows, slug) {
+  const lower = slug.toLowerCase();
+  return (
+    rows.find((row) => String(row.slug || '').toLowerCase() === lower) ||
+    rows.find((row) => String(row.name || '').toLowerCase() === lower) ||
+    null
+  );
+}
+
+async function resolveProjectBySlug(client, slug) {
+  const sites = await listAllRows(client, 'sites_list');
+  const site = matchSiteRow(sites, slug);
+  if (site) return site;
+
+  // Fall back to the PM project of that slug/name and follow its link.
+  const pmRows = await listAllRows(client, 'list_projects');
+  const pmRow = matchPmRow(pmRows, slug);
+  const linkedId = linkedWebsiteId(pmRow);
+  if (linkedId) {
+    const linked = await lookupRow(client, 'project_get', { project_id: linkedId });
+    if (linked) return linked;
+    throw new Error(
+      `"${slug}" is the PM project "${pmRow.name || slug}" (pm_projects), which links website project ${linkedId}, ` +
+        `but project_get finds no website project with that id. ${PROJECTS_HINT}`,
+    );
+  }
+  if (pmRow) {
+    throw new Error(
+      `"${slug}" is the PM project "${pmRow.name || slug}" (pm_projects) and it links no website project. ` +
+        `hiveku-sync pulls code from website projects (website_projects, sites_list). ${PROJECTS_HINT}`,
+    );
   }
-  return match;
+  throw new Error(
+    `No website project matching "${slug}": nothing in sites_list has that subdomain or name, and no PM project ` +
+      `(list_projects) with that slug or name links a website project. ${PROJECTS_HINT}`,
+  );
+}
+
+/**
+ * Resolve a website project (website_projects row) from a UUID or a slug.
+ * A UUID is tried as a website id (project_get) and then as a PM id
+ * (get_project → website_project_id → project_get). A slug is matched against
+ * sites_list (subdomain, then name) and then against list_projects
+ * (slug, then name) → its linked website project. The row returned always
+ * carries project_type and external_platform for refuseExternal.
+ */
+export async function resolveProject(client, slugOrId) {
+  if (UUID_RE.test(slugOrId)) return resolveProjectByUuid(client, slugOrId);
+  return resolveProjectBySlug(client, slugOrId);
 }
 
-export async function runProjectsList({ profile } = {}) {
-  const { client } = await clientFromCwd({ profileOverride: profile });
-  const result = await client.callToolJson('list_projects', {});
-  const list = result?.data || [];
-  if (list.length === 0) {
-    console.log('No projects on this account.');
+export async function runProjectsList({ profile, client: injectedClient } = {}) {
+  const { client } = await resolveClient({ client: injectedClient, profile });
+  const sites = await listAllRows(client, 'sites_list');
+  if (sites.length === 0) {
+    console.log('No website projects on this account.');
     return;
   }
-  console.log(`${list.length} project${list.length !== 1 ? 's' : ''}:\n`);
-  for (const p of list) {
-    const type = p.project_type || '?';
-    const slug = p.slug || p.name || p.id;
-    console.log(`  ${slug.padEnd(32)} ${type.padEnd(14)} ${p.id}`);
+  console.log(`${sites.length} website project${sites.length !== 1 ? 's' : ''}:\n`);
+  for (const site of sites) {
+    const type = site.project_type || '?';
+    const handle = site.subdomain || site.name || site.id;
+    const nameColumn = site.name && site.name !== handle ? `  ${site.name}` : '';
+    console.log(`  ${handle.padEnd(32)} ${type.padEnd(14)} ${site.id}${nameColumn}`);
   }
 }
 
-export async function runPullProject({ slugOrId, profile, branch }) {
+export async function runPullProject({ slugOrId, profile, branch, client: injectedClient, baseDir: baseDirOverride }) {
   if (!slugOrId) throw new Error('Provide a project slug or UUID');
-  const { client, baseDir } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride });
   const project = await resolveProject(client, slugOrId);
+  // An external site has no file tree: the pull would write nothing and stamp
+  // a RUN.md that says "unknown project type". Refuse before the first file call.
+  refuseExternal(project);
   const projectId = project.id;
   const localSlug = safeSlug(project.slug || project.name || projectId);
   const dest = join(baseDir, PROJECTS_DIR, localSlug);
@@ -259,6 +464,7 @@ export async function runPullProject({ slugOrId, profile, branch }) {
     project_id: projectId,
     name: project.name || project.slug || localSlug,
     project_type: project.project_type || null,
+    external_platform: project.external_platform || null,
     branch: branch || null,
     last_pull_at: new Date().toISOString(),
   };
@@ -301,16 +507,17 @@ function summarizeDiff(diff) {
   };
 }
 
-export async function runProjectStatus({ slug, profile, json = false }) {
+export async function runProjectStatus({ slug, profile, json = false, client: injectedClient, baseDir: baseDirOverride }) {
   // Resolve baseDir as the account folder. If we're inside ./projects/<x>/,
   // walk up two levels. Otherwise treat cwd as the account folder.
   const cwd = process.cwd();
   const projectsIdx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
-  const baseDir =
+  const detectedBaseDir =
     projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
 
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride || detectedBaseDir });
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  refuseExternal(info);
 
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
@@ -387,6 +594,8 @@ export async function runProjectPush({
   profile,
   includeDeletes = false,
   dryRun = false,
+  client: injectedClient,
+  baseDir: baseDirOverride,
 }) {
   if (!message || !message.trim()) {
     throw new Error('Provide a commit message via -m "..."');
@@ -394,10 +603,11 @@ export async function runProjectPush({
 
   const cwd = process.cwd();
   const projectsIdx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
-  const baseDir = projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
+  const detectedBaseDir = projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
 
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride || detectedBaseDir });
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  refuseExternal(info);
 
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);

package/src/pull.mjs

@@ -2,6 +2,11 @@
  * `hiveku-sync pull` — fetches memory/rules/skills via the MCP memory_list tool
  * and writes them as local .md files under the current folder.
  *
+ * The account memory (domains `account` and `account-suggestions`) is not a
+ * knowledge entry: it is classified explicitly, never written under memory/,
+ * and pulled once from account_memory_get into a read-only
+ * hiveku-data/account/ACCOUNT_MEMORY.md (see account-memory.mjs).
+ *
  * Safety: refuses to overwrite when the .env API key no longer matches the
  * manifest's recorded key preview (prevents pulling Account A's data into a
  * folder previously synced for Account B — the 2026-05-11 cross-tenant bug
@@ -22,6 +27,15 @@ import {
   TYPE_TO_FOLDER,
   SUPPORTED_TYPES,
 } from './util.mjs';
+import {
+  ACCOUNT_MEMORY_FILE,
+  classifyMemoryEntry,
+  ACCOUNT_MEMORY_TOOL,
+  normalizeAccountMemory,
+  renderAccountMemoryFile,
+  resolveAccountId,
+  writeReadOnly,
+} from './account-memory.mjs';
 
 const MANIFEST_PATH = '.hiveku/manifest.json';
 
@@ -58,7 +72,19 @@ function renderEntry(entry, type) {
   return `${frontmatter}${body}`;
 }
 
-export async function runPull({ baseDir = process.cwd(), profile } = {}) {
+/**
+ * Write hiveku-data/account/ACCOUNT_MEMORY.md from account_memory_get, read-only.
+ * Returns { file, version, suggestions, accountId }, or throws (the caller
+ * records the error and keeps the previous copy).
+ */
+export async function pullAccountMemory({ client, baseDir, fetchedAt = new Date().toISOString() }) {
+  const memory = normalizeAccountMemory(await client.callToolJson(ACCOUNT_MEMORY_TOOL, {}));
+  const accountId = await resolveAccountId(client);
+  await writeReadOnly(join(baseDir, ACCOUNT_MEMORY_FILE), renderAccountMemoryFile({ memory, accountId, fetchedAt }));
+  return { file: ACCOUNT_MEMORY_FILE, version: memory.version, suggestions: memory.suggestions.length, accountId };
+}
+
+export async function runPull({ baseDir = process.cwd(), profile, client: injectedClient } = {}) {
   const envPath = join(baseDir, '.env');
   const dotenv = await loadDotenv(envPath);
   const apiKey = readEnv(process.env, dotenv, 'OLYMPUS_API_KEY');
@@ -88,10 +114,10 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
     );
   }
 
-  const client = new HivekuMcpClient({ baseUrl, apiKey, profile: activeProfile });
-  await client.initialize();
+  const client = injectedClient || new HivekuMcpClient({ baseUrl, apiKey, profile: activeProfile });
+  if (!injectedClient) await client.initialize();
 
-  const summary = { total: 0, by_type: {}, errors: [] };
+  const summary = { total: 0, by_type: {}, errors: [], account_memory: null, account_rows_skipped: 0 };
   const writtenFiles = new Set();
 
   for (const type of SUPPORTED_TYPES) {
@@ -103,10 +129,19 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
       summary.errors.push({ type, message: err.message });
       continue;
     }
-    summary.by_type[type] = entries.length;
-    summary.total += entries.length;
-
+    // The two account-memory domains are not knowledge entries: an older
+    // server still lists them, and they would land as memory/account.md and
+    // memory/account-suggestions.md (raw JSON Lines) looking editable. They
+    // are written once, read-only, from account_memory_get below.
+    const knowledge = [];
     for (const entry of entries) {
+      if (classifyMemoryEntry(entry, folder).kind === 'knowledge') knowledge.push(entry);
+      else summary.account_rows_skipped += 1;
+    }
+    summary.by_type[type] = knowledge.length;
+    summary.total += knowledge.length;
+
+    for (const entry of knowledge) {
       const filename = entryFilename(entry);
       const fullPath = join(baseDir, folder, filename);
       await writeFileAtomic(fullPath, renderEntry(entry, type));
@@ -114,6 +149,17 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
     }
   }
 
+  // The account memory: one read-only file, never uploaded by anything here.
+  // A failure keeps the previous copy (and its manifest line), so it is not
+  // reported as removed upstream.
+  try {
+    summary.account_memory = await pullAccountMemory({ client, baseDir });
+    writtenFiles.add(ACCOUNT_MEMORY_FILE);
+  } catch (err) {
+    summary.errors.push({ type: 'account memory', message: err.message });
+    if ((manifest?.files ?? []).includes(ACCOUNT_MEMORY_FILE)) writtenFiles.add(ACCOUNT_MEMORY_FILE);
+  }
+
   // v1: don't delete stale files; just record them in the manifest so the
   // user can prune manually if they want. Avoids losing local edits.
   const previouslySeen = new Set(manifest?.files ?? []);
@@ -129,6 +175,8 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
         last_sync_at: new Date().toISOString(),
         counts: summary.by_type,
         files: [...writtenFiles].sort(),
+        // Pulled for reading only: edited on the dashboard, never uploaded.
+        read_only: [ACCOUNT_MEMORY_FILE],
         removed_remotely_since_last_sync: removedRemotely,
       },
       null,

package/src/push.mjs

@@ -28,6 +28,7 @@ import { join, relative, sep } from 'node:path';
 import {
   clientFromCwd,
   findProjectFolder,
+  refuseExternal,
   resolveProject,
   walkLocalFiles,
   readProjectsManifest,
@@ -225,10 +226,13 @@ export async function computePushPlan({ client, projectId, folder, includeDelete
 
 // Thin CLI wrapper: resolve the MCP client + project folder from cwd, then run
 // the (fully testable) orchestration in pushProject.
-export async function runPush({ slug, profile, ...opts } = {}) {
-  const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
+export async function runPush({ slug, profile, client: injectedClient, baseDir: baseDirOverride, ...opts } = {}) {
+  const baseDir = baseDirOverride || resolveBaseDir();
+  const client = injectedClient || (await clientFromCwd({ profileOverride: profile })).client;
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  // An external site (Webflow, WordPress, any tracked host) has no deploy
+  // source to push to; refuse before the diff.
+  refuseExternal(info);
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
   }
@@ -500,22 +504,32 @@ async function runDeployFor({ client, projectId, slug, environment, wait }) {
   return { deployment_id: deploymentId, environment: env, status: last, waited: true, ok: false };
 }
 
-export async function runDeploy({ slugOrId, environment, wait = false, profile }) {
+export async function runDeploy({ slugOrId, environment, wait = false, profile, client: injectedClient, baseDir: baseDirOverride }) {
   if (!environment) throw new Error('Usage: hiveku-sync deploy <development|staging|production> [<slug>] [--wait]');
-  const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const baseDir = baseDirOverride || resolveBaseDir();
+  const client = injectedClient || (await clientFromCwd({ profileOverride: profile })).client;
 
   // Resolve project: prefer the pulled-folder manifest (slug), else treat the
-  // arg as a slug/UUID via list_projects.
+  // arg as a slug/UUID via resolveProject (project_get / sites_list, the
+  // website_projects id space - not the PM tools). Either way an external site has
+  // nothing to deploy (deploy_site 400s on project_type external) - refuse
+  // with the pointer to where it IS managed.
   let projectId;
   let slug = slugOrId;
+  let found;
   try {
-    const { slug: s, info } = await findProjectFolder({ slug: slugOrId, baseDir });
-    projectId = info.project_id;
-    slug = s;
+    found = await findProjectFolder({ slug: slugOrId, baseDir });
   } catch {
+    found = null;
+  }
+  if (found) {
+    refuseExternal(found.info);
+    projectId = found.info.project_id;
+    slug = found.slug;
+  } else {
     if (!slugOrId) throw new Error('No project folder detected — pass a project slug or UUID: hiveku-sync deploy <env> <slug>');
     const project = await resolveProject(client, slugOrId);
+    refuseExternal(project);
     projectId = project.id;
     slug = project.slug || project.name || project.id;
   }
@@ -587,8 +601,12 @@ export async function runPullEnv({ slug, profile, target = 'development' } = {})
 
   const res = (await client.callToolJson('project_secrets_list', { project_id: projectId })).data;
   const secrets = res?.secrets || {};
+  // Variables marked sensitive are write-only on the platform: the server OMITS them
+  // from `secrets` and lists their names here. Without saying so, the .env file below
+  // would be silently incomplete and the user would go debugging a phantom.
+  const sensitiveKeys = Array.isArray(res?.sensitive_keys) ? res.sensitive_keys : [];
   const count = Object.keys(secrets).length;
-  if (count === 0) {
+  if (count === 0 && sensitiveKeys.length === 0) {
     console.log(`No secrets set on ${resolvedSlug}. Nothing to write.`);
     return { written: 0 };
   }
@@ -614,5 +632,12 @@ export async function runPullEnv({ slug, profile, target = 'development' } = {})
   }
 
   console.log(`Wrote ${Object.keys(resolved).length} var${Object.keys(resolved).length !== 1 ? 's' : ''} → ${outName} (tier: ${tier}, from ${count} secret${count !== 1 ? 's' : ''}).`);
-  return { written: Object.keys(resolved).length, path: outPath, tier };
+  if (sensitiveKeys.length > 0) {
+    const names = sensitiveKeys.slice().sort();
+    console.log(
+      `Skipped ${names.length} sensitive var${names.length !== 1 ? 's' : ''}: ${names.join(', ')}.`,
+    );
+    console.log('These are write-only on Hiveku and cannot be read back. Set them by hand if your local build needs them.');
+  }
+  return { written: Object.keys(resolved).length, skippedSensitive: sensitiveKeys, path: outPath, tier };
 }