@zeyos/client 0.2.0 → 0.4.0

package/src/runtime/client.js

@@ -56,8 +56,14 @@ function abortableDelay(ms, signal) {
   });
 }
 
-// Honor a Retry-After header (seconds or HTTP-date), else exponential backoff
-// with jitter, capped at maxDelayMs.
+// Exponential backoff with jitter, capped at maxDelayMs.
+function backoffDelay(attempt, retryConfig) {
+  const exp = retryConfig.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * retryConfig.baseDelayMs;
+  return Math.min(retryConfig.maxDelayMs, exp + jitter);
+}
+
+// Honor a Retry-After header (seconds or HTTP-date), else exponential backoff.
 function computeRetryDelay(response, attempt, retryConfig) {
   const header = response.headers?.['retry-after'];
   // An empty or whitespace-only header carries no delay directive — `Number('')`
@@ -74,9 +80,88 @@ function computeRetryDelay(response, attempt, retryConfig) {
       return Math.min(retryConfig.maxDelayMs, Math.max(0, dateMs - Date.now()));
     }
   }
-  const exp = retryConfig.baseDelayMs * Math.pow(2, attempt);
-  const jitter = Math.random() * retryConfig.baseDelayMs;
-  return Math.min(retryConfig.maxDelayMs, exp + jitter);
+  return backoffDelay(attempt, retryConfig);
+}
+
+// Operations that are safe to transparently retry on a network error / timeout:
+// HTTP GET/HEAD, plus ZeyOS read queries (list/count/search) which are POST but
+// side-effect-free. Writes (create/update/delete) are never auto-retried, so a
+// dropped connection can't cause a duplicate mutation.
+function isReadOperation(operation) {
+  const method = operation?.method;
+  if (method === 'GET' || method === 'HEAD') {
+    return true;
+  }
+  return /^(list|count|search|exists|get)/i.test(operation?.operationId || '');
+}
+
+// Build a one-line, human-readable summary from a server error body so the thrown
+// error message says *why* (e.g. an unknown-filter 400), not just the status code.
+// The full body remains available on error.body.
+function summarizeErrorBody(body, maxLength = 200) {
+  let text = '';
+  if (typeof body === 'string') {
+    text = body.trim();
+  } else if (body && typeof body === 'object') {
+    const candidate =
+      body.message ?? body.error_description ?? body.error ?? body.detail ?? body.title;
+    if (typeof candidate === 'string' && candidate.trim()) {
+      text = candidate.trim();
+    } else {
+      try {
+        text = JSON.stringify(body);
+      } catch {
+        text = '';
+      }
+    }
+  }
+  if (!text) {
+    return '';
+  }
+  return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+}
+
+// Run fetch with an optional per-attempt timeout, composed with the caller's
+// AbortSignal (Node 18 compatible — no AbortSignal.any). A timeout aborts the
+// internal controller only, so `externalSignal.aborted` stays false and the
+// caller can distinguish a timeout (retryable for reads) from a user abort.
+async function fetchWithTimeout(httpRequestImpl, requestArgs, externalSignal, timeoutMs) {
+  if (!(timeoutMs > 0)) {
+    return httpRequestImpl({ ...requestArgs, signal: externalSignal });
+  }
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const onExternalAbort = () => controller.abort(externalSignal.reason);
+
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort(externalSignal.reason);
+    } else {
+      externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+    }
+  }
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    return await httpRequestImpl({ ...requestArgs, signal: controller.signal });
+  } catch (error) {
+    if (timedOut) {
+      const timeoutError = new Error(`Request timed out after ${timeoutMs}ms`);
+      timeoutError.name = 'TimeoutError';
+      timeoutError.code = 'ETIMEDOUT';
+      timeoutError.isTimeout = true;
+      throw timeoutError;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    externalSignal?.removeEventListener?.('abort', onExternalAbort);
+  }
 }
 
 const AUTH_SCHEME_MAP = Object.freeze({
@@ -390,7 +475,8 @@ function chooseBodyType(serviceKey, operation, prepared, fallbackBodyType) {
 
 function createApiError(response, { serviceKey, operation, method, url }) {
   const operationDescription = operation.operationId ? `${serviceKey}.${operation.operationId}` : `${serviceKey} request`;
-  const message = `${operationDescription} failed with HTTP ${response.status}`;
+  const detail = summarizeErrorBody(response.data);
+  const message = `${operationDescription} failed with HTTP ${response.status}${detail ? `: ${detail}` : ''}`;
 
   return new ZeyosApiError(message, {
     status: response.status,
@@ -606,6 +692,10 @@ export function createZeyosClient(rawConfig = {}) {
 
   const defaultHeaders = isObject(config.headers) ? config.headers : {};
   const retryConfig = normalizeRetry(config.retry);
+  const defaultTimeoutMs = Number(config.timeoutMs) > 0 ? Number(config.timeoutMs) : 0;
+  // Whether to transparently retry network errors / timeouts. `undefined` (default)
+  // means "auto": retry only read operations. `true`/`false` force the behavior.
+  const defaultRetryOnNetworkError = typeof config.retryOnNetworkError === 'boolean' ? config.retryOnNetworkError : undefined;
   const schemaApi = createSchema({ services: SERVICES, schema: SCHEMA });
   const validateByDefault = config.validate === true;
   const operationLookup = new Map();
@@ -616,6 +706,10 @@ export function createZeyosClient(rawConfig = {}) {
     }
   }
 
+  // Single-flight token refresh: shared across all concurrent operations so an
+  // expired token triggers exactly one getToken call (see refreshAccessTokenOnce).
+  let refreshInFlight = null;
+
   async function getTokenSet() {
     return normalizeTokenSet(await tokenStore.get());
   }
@@ -644,6 +738,15 @@ export function createZeyosClient(rawConfig = {}) {
     return `ZEYOSID=${cookieValue}`;
   }
 
+  // Resolve whether a network error / timeout may be retried for this call.
+  // Explicit per-request / client config wins; otherwise auto = read ops only.
+  function resolveNetworkRetry(operation, requestOptions) {
+    const explicit = requestOptions?.retryOnNetworkError ?? defaultRetryOnNetworkError;
+    if (explicit === true) return true;
+    if (explicit === false) return false;
+    return isReadOperation(operation);
+  }
+
   async function sendRequestOnce({ serviceKey, operation, prepared, requestAuth, tokenSet, candidate, requestOptions }) {
     const body = cloneValue(prepared.body);
     const authHeaders = {};
@@ -698,19 +801,27 @@ export function createZeyosClient(rawConfig = {}) {
     );
 
     const signal = prepared.signal ?? requestOptions?.signal;
+    const timeoutMs = Number(requestOptions?.timeoutMs ?? defaultTimeoutMs) || 0;
+    const networkRetryAllowed = resolveNetworkRetry(operation, requestOptions);
+    const requestArgs = { fetchImpl, url, method: operation.method, headers, body, bodyType, credentials };
 
     let response;
     for (let attempt = 0; ; attempt++) {
-      response = await httpRequest({
-        fetchImpl,
-        url,
-        method: operation.method,
-        headers,
-        body,
-        bodyType,
-        signal,
-        credentials
-      });
+      try {
+        response = await fetchWithTimeout(httpRequest, requestArgs, signal, timeoutMs);
+      } catch (error) {
+        // A caller-initiated abort must never be retried — propagate immediately.
+        // (A timeout aborts only the internal controller, so signal.aborted is false.)
+        if (signal?.aborted) {
+          throw error;
+        }
+        // Network error or timeout: retry only safe (read) operations, within budget.
+        if (!networkRetryAllowed || attempt >= retryConfig.maxRetries) {
+          throw error;
+        }
+        await abortableDelay(backoffDelay(attempt, retryConfig), signal);
+        continue;
+      }
 
       if (attempt >= retryConfig.maxRetries || !retryConfig.retryOn.has(response.status)) {
         break;
@@ -787,6 +898,22 @@ export function createZeyosClient(rawConfig = {}) {
     return nextTokenSet;
   }
 
+  // Single-flight wrapper: when several operations notice an expired token at the
+  // same time (e.g. `Promise.all([...])`), they must share ONE refresh. Without
+  // this each fires its own getToken — redundant load, and a hard failure when the
+  // server rotates refresh tokens (all but the first present a stale refresh token).
+  function refreshAccessTokenOnce(currentTokenSet, requestAuth, requestOptions) {
+    if (refreshInFlight) {
+      return refreshInFlight;
+    }
+    refreshInFlight = Promise.resolve()
+      .then(() => refreshAccessToken(currentTokenSet, requestAuth, requestOptions))
+      .finally(() => {
+        refreshInFlight = null;
+      });
+    return refreshInFlight;
+  }
+
   async function executeOperation({ serviceKey, operation, prepared, requestOptions = {} }) {
     // Dry run: resolve the route + payload exactly as they would be sent, but
     // return that descriptor instead of performing any network request or token
@@ -826,7 +953,7 @@ export function createZeyosClient(rawConfig = {}) {
       canRefreshAccessToken({ mode, operation, tokenSet, oauthConfig })
     ) {
       try {
-        const refreshed = await refreshAccessToken(tokenSet, requestAuth, requestOptions);
+        const refreshed = await refreshAccessTokenOnce(tokenSet, requestAuth, requestOptions);
         if (refreshed?.accessToken) {
           tokenSet = refreshed;
         }
@@ -865,7 +992,7 @@ export function createZeyosClient(rawConfig = {}) {
 
         if (candidate.type === 'bearer' && canRefreshAccessToken({ mode, operation, tokenSet, oauthConfig })) {
           try {
-            const refreshed = await refreshAccessToken(tokenSet, requestAuth, requestOptions);
+            const refreshed = await refreshAccessTokenOnce(tokenSet, requestAuth, requestOptions);
             if (refreshed?.accessToken) {
               tokenSet = refreshed;
               const retryResponse = await sendRequestOnce({
@@ -1017,6 +1144,58 @@ export function createZeyosClient(rawConfig = {}) {
   const oauth2Operations = bindService('oauth2');
   const legacyAuth = bindService('legacyAuth');
 
+  // Async-iterate every record from a list operation, paging by `offset` until a
+  // short/empty page (or `opts.max`) is reached — removing the manual offset
+  // bookkeeping the 1000/10000 list caps otherwise force on callers.
+  //
+  //   for await (const ticket of client.paginate('listTickets', { filters: { visibility: 0 } })) { … }
+  //
+  async function* paginate(operationId, input = {}, opts = {}) {
+    const op = operationLookup.get(`api.${operationId}`);
+    if (!op) {
+      const candidates = (SERVICES.api?.operations ?? []).map((entry) => entry.operationId);
+      const suggestion = suggestClosest(operationId, candidates);
+      throw new ZeyosApiError(
+        `Unknown list operation: api.${operationId}.` + (suggestion ? ` Did you mean '${suggestion}'?` : ''),
+        { operationId, service: 'api' }
+      );
+    }
+
+    const requested = Number(opts.pageSize) > 0 ? Number(opts.pageSize)
+      : Number(input.limit) > 0 ? Number(input.limit) : 1000;
+    // Clamp to the server's max page size: a larger request would be silently
+    // capped server-side, making the short-page terminator stop early and drop rows.
+    const pageSize = Math.min(requested, 10000);
+    const max = Number(opts.max) > 0 ? Number(opts.max) : Infinity;
+    let offset = Number(input.offset) > 0 ? Number(input.offset) : 0;
+    let yielded = 0;
+
+    for (;;) {
+      const page = await api[operationId]({ ...input, limit: pageSize, offset }, opts.requestOptions);
+      const rows = Array.isArray(page) ? page : Array.isArray(page?.data) ? page.data : [];
+      for (const row of rows) {
+        yield row;
+        yielded += 1;
+        if (yielded >= max) {
+          return;
+        }
+      }
+      if (rows.length < pageSize) {
+        return; // last (short or empty) page
+      }
+      offset += pageSize;
+    }
+  }
+
+  // Eager convenience: collect up to `opts.max` records into an array.
+  async function collect(operationId, input = {}, opts = {}) {
+    const out = [];
+    for await (const row of paginate(operationId, input, opts)) {
+      out.push(row);
+    }
+    return out;
+  }
+
   function buildAuthorizationUrl(options = {}) {
     const clientId = options.clientId ?? options.client_id ?? oauthConfig.clientId;
     const redirectUri = options.redirectUri ?? options.redirect_uri;
@@ -1219,6 +1398,8 @@ export function createZeyosClient(rawConfig = {}) {
     oauth2,
     legacyAuth,
     request,
+    paginate,
+    collect,
     schema: schemaApi,
     auth: {
       getTokenSet,

package/src/runtime/okf.js

@@ -0,0 +1,237 @@
+// Open Knowledge Format (OKF v0.1) support for @zeyos/client.
+//
+// Two halves:
+//   • Pure (browser + Node): the OKF conformance constants, a tolerant concept
+//     parser, a bundle validator, and buildOkf() — which synthesizes a conformant
+//     OKF bundle from the client's own introspection surface (the generated
+//     SCHEMA + SERVICES). No filesystem access.
+//   • Node-only: loadOkfBundle() reads the shipped okf/ bundle (or any directory)
+//     from disk via a lazy import, so this module stays bundler/browser-safe.
+//
+// The richer build-time producer (scripts/generate-okf.mjs) emits the curated,
+// managed-block bundle under okf/. buildOkf() here is the lightweight runtime
+// projection of what the shipped client knows — handy for emitting OKF in
+// environments without the bundled files, or to diff against a live instance.
+
+import { SCHEMA } from '../generated/schema.js';
+import { SERVICES } from '../generated/operations.js';
+
+export const OKF_VERSION = '0.1';
+
+// Markers fencing producer-generated content inside a concept's body. Exported so
+// the build-time renderer (scripts/lib/okf.mjs) shares one definition.
+export const GENERATED_START = '<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->';
+export const GENERATED_END = '<!-- okf:generated:end -->';
+export const GENERATED_FRONTMATTER_KEYS = Object.freeze([
+  'type', 'title', 'description', 'resource', 'tags', 'timestamp',
+  'api_backed', 'list_operation', 'visibility_column'
+]);
+
+// Files that are not concept documents (spec §5/§6).
+const RESERVED_BASENAMES = new Set(['index.md', 'log.md']);
+
+const VERB_RE = /^(list|get|create|update|delete|exists)/;
+
+// ── Parsing / validation (pure) ────────────────────────────────────────────────
+
+/** Tolerant frontmatter + body split. Returns `{ frontmatter, body }` where
+ *  frontmatter is a flat string→string map (lists kept as their raw text). */
+export function parseConcept(content) {
+  const text = String(content || '');
+  const match = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!match) return { frontmatter: {}, body: text };
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_]+):\s*(.*)$/.exec(line);
+    if (kv) frontmatter[kv[1]] = kv[2].trim();
+  }
+  return { frontmatter, body: text.slice(match[0].length) };
+}
+
+function isReserved(relPath) {
+  const base = relPath.split('/').pop();
+  return RESERVED_BASENAMES.has(base);
+}
+
+/**
+ * Validate an OKF bundle for v0.1 conformance (spec §9): every non-reserved `.md`
+ * file must have parseable frontmatter with a non-empty `type`. Tolerant by
+ * design — unknown types/keys and broken links are NOT errors.
+ *
+ * @param {Record<string,string>} files - relativePath → file content.
+ * @returns {{ valid: boolean, errors: { path: string, message: string }[], conceptCount: number }}
+ */
+export function validateOkfFiles(files) {
+  const errors = [];
+  let conceptCount = 0;
+  for (const [relPath, content] of Object.entries(files || {})) {
+    if (!relPath.endsWith('.md') || isReserved(relPath)) continue;
+    conceptCount += 1;
+    const { frontmatter } = parseConcept(content);
+    if (!Object.keys(frontmatter).length) {
+      errors.push({ path: relPath, message: 'Missing YAML frontmatter.' });
+      continue;
+    }
+    if (!frontmatter.type) {
+      errors.push({ path: relPath, message: 'Frontmatter is missing the required `type` field.' });
+    }
+  }
+  return { valid: errors.length === 0, errors, conceptCount };
+}
+
+/** The OKF concept ID for a ZeyOS resource, e.g. `tickets` → `entities/tickets`. */
+export function conceptIdForResource(resource) {
+  return `entities/${resource}`;
+}
+
+// ── buildOkf: synthesize a bundle from the client's introspection surface ───────
+
+function groupOperations(services) {
+  const byResource = new Map();
+  for (const service of Object.values(services || {})) {
+    for (const op of service.operations || []) {
+      const resource = resourceFromPath(op.path);
+      if (!resource) continue;
+      if (!byResource.has(resource)) byResource.set(resource, {});
+      const bucket = byResource.get(resource);
+      const m = VERB_RE.exec(op.operationId);
+      const key = m ? m[1] : op.operationId;
+      if (!bucket[key]) bucket[key] = op.operationId;
+    }
+  }
+  return byResource;
+}
+
+function resourceFromPath(p) {
+  if (typeof p !== 'string') return null;
+  for (const segment of p.split('/')) {
+    if (segment && !segment.startsWith('{')) return segment;
+  }
+  return null;
+}
+
+function titleFromOps(ops, fallback) {
+  const op = ops.list || ops.get;
+  if (!op) return fallback.charAt(0).toUpperCase() + fallback.slice(1);
+  return op.replace(VERB_RE, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').trim() || fallback;
+}
+
+// Deterministic, dependency-free 32-bit hash for the bundle source snapshot.
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+function renderEntityDoc(name, entry, ops, hasDoc) {
+  const link = (target) => (hasDoc.has(target) ? `/entities/${target}.md` : null);
+  const fields = Object.entries(entry.fields || {});
+
+  const schemaRows = fields.map(([fname, def]) => {
+    const fkCell = def.fk ? (link(def.fk) ? `[${def.fk}](${link(def.fk)})` : def.fk) : '—';
+    const enumCell = def.enum ? Object.entries(def.enum).map(([k, v]) => `${k}=${v}`).join(', ') : '—';
+    return `| \`${fname}\` | ${def.type || 'unknown'} | ${def.indexed ? 'yes' : '—'} | ${fkCell} | ${enumCell} |`;
+  });
+  const schema = `# Schema\n\n| Column | Type | Indexed | FK | Enum |\n|---|---|---|---|---|\n${schemaRows.join('\n')}`;
+
+  const fks = fields.filter(([, d]) => d.fk);
+  const fkSection = fks.length
+    ? `\n\n# Foreign Keys\n\n${fks.map(([f, d]) => `- \`${f}\` → ${link(d.fk) ? `[${d.fk}](${link(d.fk)})` : d.fk}`).join('\n')}`
+    : '';
+
+  const order = ['list', 'get', 'create', 'update', 'delete', 'exists'];
+  const opLines = order.filter((k) => ops[k]).map((k) => `- ${k}: \`${ops[k]}\``);
+  const opSection = opLines.length ? `\n\n# Operations\n\n${opLines.join('\n')}` : '';
+
+  const title = titleFromOps(ops, name);
+  const fm = [
+    'type: ZeyOS Entity',
+    `title: ${title}`,
+    `resource: zeyos://api/${name}`,
+    'tags: [generated]',
+    'api_backed: true'
+  ];
+  if (ops.list) fm.push(`list_operation: ${ops.list}`);
+  fm.push(`visibility_column: ${Object.prototype.hasOwnProperty.call(entry.fields || {}, 'visibility')}`);
+
+  return `---\n${fm.join('\n')}\n---\n\n${schema}${fkSection}${opSection}\n`;
+}
+
+/**
+ * Synthesize a conformant OKF v0.1 bundle from a client schema + services. Pure:
+ * returns a `{ relativePath: content }` map; the caller decides whether to write
+ * it to disk. Defaults to the generated SCHEMA/SERVICES baked into the client.
+ *
+ * @param {{ schema?: object, services?: object }} [input]
+ * @returns {Record<string,string>}
+ */
+export function buildOkf({ schema = SCHEMA, services = SERVICES } = {}) {
+  const ops = groupOperations(services);
+  const resources = Object.keys(schema).filter((r) => ops.has(r)).sort();
+  const hasDoc = new Set(resources);
+  const files = {};
+
+  for (const name of resources) {
+    files[`entities/${name}.md`] = renderEntityDoc(name, schema[name], ops.get(name) || {}, hasDoc);
+  }
+
+  const indexItems = resources
+    .map((name) => `* [${titleFromOps(ops.get(name) || {}, name)}](${name}.md)`)
+    .join('\n');
+  files['entities/index.md'] = `# Entities\n\n${indexItems}\n`;
+
+  const signature = resources.map((r) => `${r}:${Object.keys(schema[r].fields || {}).join(',')}`).join('|');
+  files['index.md'] = `---\nokf_version: ${OKF_VERSION}\nsource_snapshot: ${fnv1a(signature)}\n---\n\n# ZeyOS Knowledge Bundle\n\n* [Entities](entities/) - ${resources.length} API-backed entity concepts.\n`;
+
+  return files;
+}
+
+// ── Node-only loaders (lazy fs so the module stays browser-safe) ────────────────
+
+/**
+ * Read an OKF bundle directory from disk. Node only.
+ * @param {string} dir - Path to a bundle root (e.g. the shipped okf/).
+ * @returns {Promise<{ version: string|null, files: Record<string,string>, concepts: Record<string,{frontmatter:object,body:string}> }>}
+ */
+export async function loadOkfBundle(dir) {
+  const { readFile, readdir } = await import('node:fs/promises');
+  const path = await import('node:path');
+
+  const files = {};
+  async function walk(current, prefix) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = path.join(current, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await walk(abs, rel);
+      else if (entry.name.endsWith('.md')) files[rel] = await readFile(abs, 'utf8');
+    }
+  }
+  await walk(dir, '');
+
+  const concepts = {};
+  for (const [rel, content] of Object.entries(files)) {
+    if (isReserved(rel)) continue;
+    concepts[rel.replace(/\.md$/, '')] = parseConcept(content);
+  }
+
+  let version = null;
+  if (files['index.md']) version = parseConcept(files['index.md']).frontmatter.okf_version || null;
+
+  return { version, files, concepts };
+}
+
+/**
+ * Validate an OKF bundle. Accepts a directory path (Node) or an in-memory
+ * `{ path: content }` map (universal). Returns the validateOkfFiles() result.
+ */
+export async function validateOkfBundle(dirOrFiles) {
+  if (typeof dirOrFiles === 'string') {
+    const { files } = await loadOkfBundle(dirOrFiles);
+    return validateOkfFiles(files);
+  }
+  return validateOkfFiles(dirOrFiles);
+}

package/samples/missioncontrol/README.md

@@ -1,106 +0,0 @@
-# Mission Control
-
-A team-performance dashboard for an IT consultancy running on ZeyOS — built on
-the [`@zeyos/client`](../../README.md) library. It answers the managing
-director's question: **who is actually working, and where is there untapped
-capacity?**
-
-A dark "mission control" view: a velocity KPI row, a 13-week throughput trend,
-a team-capacity strip, and a searchable/sortable/filterable grid of per-employee
-activity cards (click one for a per-type digest + contribution graph).
-
-## What it shows
-
-1. **Velocity** — tickets opened vs closed in the window, net flow, average /
-   median / p90 **cycle time** (open → close), open backlog (with overdue), and
-   total **hours booked**. A 13-week **throughput trend** of opened vs closed.
-2. **Activity card per employee** — open tickets, open tasks, tickets closed,
-   hours booked, a weekly-hours sparkline, team/location tags, a **capacity
-   badge** (Overloaded / Balanced / Available / Idle / Former), and **last
-   activity** (the most recent time entry) — flagged red when it's **older than
-   7 days**. Hover "last activity" to see the engineer's **last 10 time entries**
-   (date · type · customer · ticket · hours).
-3. **Per-employee digest** (click a card) — **booked hours stacked by
-   `extdata.type`** (Weekly / Monthly), and a **GitHub-style contribution graph**
-   of their time-entry activity over the last 53 weeks.
-
-Filters: search by name, **filter by team / department / location** (group
-membership), capacity chips (Engaged / Spare capacity / Inactive >7d /
-Overloaded / All), and sort by activity, hours, throughput, workload, cycle,
-overdue, or least-recent.
-
-The **Team capacity** strip and the *Spare capacity* filter surface the
-"untapped resources": active engineers running light or with no load at all,
-contrasted with the overloaded ones — the clearest place to rebalance work.
-
-## Run it
-
-```bash
-# 1. Authenticate once (if you haven't already)
-zeyos login --base-url https://zeyos.cms-it.de/dev
-
-# 2. Pull live data into data.js (read-only; reuses your CLI credentials)
-node samples/missioncontrol/fetch-data.mjs            # 90-day window
-node samples/missioncontrol/fetch-data.mjs --days 180 # custom window
-
-# 3. Open the dashboard
-#    Either open index.html directly, or serve the folder:
-python3 -m http.server 8765 --directory samples/missioncontrol
-#    → http://localhost:8765
-```
-
-`fetch-data.mjs` writes `data.js` (a `window.MISSION_DATA = …` assignment) so
-`index.html` works straight from disk — no server, no CORS, no token pasting.
-Re-run the fetcher to refresh; the page is otherwise a static, dependency-free
-single file (hand-rolled CSS + inline-SVG charts).
-
-## How it works
-
-`fetch-data.mjs` reads the credentials `zeyos login` stored
-(`.zeyos/auth.json` or `~/.config/zeyos/credentials.json`), builds an
-auto-refreshing client with `createZeyosClient`, and issues a handful of
-**read-only** `list` queries (tickets, `actionsteps`, tasks, groups), then
-aggregates them client-side (ZeyOS has no server-side group-by). It never writes
-to ZeyOS.
-
-### Metric definitions (so the numbers are reproducible)
-
-| Metric | Definition |
-|--------|------------|
-| **Time entry** | an `actionsteps` row with `status IN [1, 3]` (COMPLETED + BOOKED), attributed to an engineer via **`assigneduser`** (`owneruser` is unused here). `effort` is in **minutes**. |
-| **Last activity** | the engineer's most recent time-entry `date`; **stale** (red ⚠) when it's >7 days before the "as of" date. |
-| **Type** | `extdata.type` of each time entry (Intern / Auftrag / Consulting / Wartung / …), selected on `list` via the `extdata.type` field. Top 6 are charted; the rest roll into *Other*. |
-| **Closed / done** | tickets with `status IN [9, 11]` — COMPLETED + BOOKED (BOOKED, completed & billed, is the dominant terminal state). |
-| **Open backlog** | `status IN [0, 1, 2, 4, 6, 7]` — started/accepted/active but not done. |
-| **Opened in window** | tickets whose indexed `date` falls in the window. |
-| **Cycle time** | `lastmodified − creationdate` for tickets closed in the window (a proxy for the close timestamp, which ZeyOS does not store separately). |
-| **Capacity** | relative to the engaged-and-active cohort: *overloaded* (top-quintile workload or ≥3 overdue), *available* (low workload **and** below-median throughput), *idle* (active user, zero load), *balanced* (else), *former* (deactivated user with leftover assignments). |
-| **Team / location** | the engineer's **group memberships** (see below). |
-
-### Notes & limitations
-
-- **Department/location = groups.** ZeyOS *defines* custom fields
-  `users.department`/`users.location`/`users.team`, but the API returns
-  *"Extension data not available for users"* — they can't be read. The org
-  structure instead lives in **group membership** (e.g. `Developers`,
-  `Services`, `Technik`, `Berlin`, `Bayern`, `Nordrhein-Westfalen`), which is
-  what the team/location filter uses.
-- **`extdata` only lists via dot-fields.** Custom fields aren't returned by a
-  plain `list` (or `extdata=1`); they must be selected explicitly, e.g.
-  `fields: ['…','extdata.type']` (returned as `extdata_type`). On single records
-  `getTicket(…, { query:{ extdata:1 } })` returns them under an `extdata` object.
-- **Corrupt time-entry dates.** Many `actionsteps` have far-future `date` values
-  (year 2099+); the fetcher bounds queries to `date ≤ now` to exclude them.
-- **"As of" anchoring.** Windows are measured back from the latest activity in
-  the data, not wall-clock today — so a frozen/dev snapshot still produces
-  meaningful windows (and the 7-day staleness check is relative to it). The
-  anchor date is shown in the header.
-- **`date`, not `creationdate`, for windows.** `creationdate`/`lastmodified` are
-  unindexed on `tickets`; range-scanning them can time out (HTTP 503). The
-  indexed `date` column is used for opened-in-window queries.
-- **Roles aren't distinguished.** Every active user is included; a salesperson
-  with no tickets shows as *Idle*. Use the team filter / search to focus on a
-  delivery team.
-
-> `data.js` / `data.json` are generated and contain real names from your
-> instance — they are git-ignored. Commit only the source.