total-recall-brain 3.44.0 → 3.46.0

package/scaffold/.agent/skills/total-recall/plugins/auth/ui/home.js

@@ -0,0 +1,375 @@
+const template = document.createElement('template');
+template.innerHTML = `
+  <style>
+    :host { display:block; color:var(--color-text,#edf6f0); font:400 .9rem/1.5 var(--typography-body-font-family,system-ui); }
+    * { box-sizing:border-box; }
+    main { background:var(--color-background,#101e19); border:1px solid var(--color-outline,#3f6350); border-radius:var(--rounded-panel,.75rem); overflow:hidden; }
+    header, .body { padding:clamp(14px,3vw,26px); }
+    header { display:flex; flex-wrap:wrap; align-items:center; justify-content:space-between; gap:12px; }
+    h1,h2,p { margin:0; }
+    h1 { font-size:clamp(1.5rem,4vw,2.25rem); letter-spacing:-.035em; line-height:1.15; }
+    h2 { font-size:1.1rem; }
+    .eyebrow { color:var(--color-primary,#64e3a4); font:600 .72rem var(--typography-label-font-family,monospace); letter-spacing:.1em; margin-bottom:6px; }
+    .muted, th { color:var(--color-muted,#b1c9ba); }
+    header p:last-child { margin-top:6px; }
+    nav { display:flex; flex-wrap:wrap; gap:4px; padding:0 clamp(14px,3vw,26px); border-block-end:1px solid var(--color-outline,#3f6350); }
+    button, input { font:inherit; color:inherit; }
+    button { min-height:44px; cursor:pointer; padding:0 12px; background:var(--color-surface,#192d24); border:1px solid var(--color-outline,#3f6350); border-radius:var(--rounded-control,.4rem); }
+    button:disabled { opacity:.65; cursor:wait; }
+    nav button { background:transparent; border:1px solid transparent; border-radius:0; color:var(--color-muted,#b1c9ba); }
+    nav button[aria-pressed="true"] { color:var(--color-primary,#64e3a4); border-block-end:2px solid currentColor; font-weight:700; }
+    button:focus-visible, input:focus-visible { outline:2px solid var(--color-primary,#64e3a4); outline-offset:2px; }
+    .tools { display:flex; align-items:center; justify-content:space-between; gap:12px; flex-wrap:wrap; margin-bottom:12px; }
+    label { display:flex; flex-wrap:wrap; align-items:center; gap:8px; }
+    input { background:var(--color-surface,#192d24); border:1px solid var(--color-outline,#3f6350); border-radius:var(--rounded-control,.4rem); min-height:44px; padding:6px 10px; max-width:100%; }
+    .table { overflow:auto; max-height:430px; }
+    table { width:100%; border-collapse:collapse; text-align:start; }
+    th, td { padding:9px 10px; text-align:start; border-block-end:1px solid var(--color-outline,#3f6350); vertical-align:top; }
+    th { position:sticky; top:0; background:var(--color-surface,#192d24); font-size:.75rem; }
+    td { overflow-wrap:anywhere; }
+    td.actions { white-space:nowrap; }
+    td.actions button + button { margin-inline-start:6px; }
+    select { font:inherit; min-height:44px; color:inherit; background:var(--color-surface,#192d24); border:1px solid var(--color-outline,#3f6350); border-radius:var(--rounded-control,.4rem); padding:6px 10px; }
+    dialog { color:inherit; background:var(--color-background,#101e19); border:1px solid var(--color-outline,#3f6350); border-radius:var(--rounded-panel,.75rem); padding:20px; width:min(480px,calc(100% - 26px)); max-height:calc(100% - 26px); }
+    dialog::backdrop { background:#08110dcc; }
+    dialog label { display:grid; margin:10px 0; }
+    dialog .tools { margin:12px 0 0; }
+    .state-ready { color:var(--color-primary,#64e3a4); }
+    .state-attention { color:var(--color-warning,#f4d18c); }
+    [role="alert"] { color:var(--color-danger,#ffbbb1); }
+    dl { margin:0 0 16px; }
+    dl div { display:flex; justify-content:space-between; flex-wrap:wrap; padding:8px 0; border-block-end:1px solid var(--color-outline,#3f6350); }
+    dd { margin:0; }
+    #audit-result { margin:8px 0; }
+    [hidden] { display:none!important; }
+  </style>
+  <main aria-labelledby="auth-title">
+    <header>
+      <div><p class="eyebrow">ACCESS CONTROL</p><h1 id="auth-title">Auth &amp; Secrets</h1>
+      <p class="muted">Credentials and access across this host’s brains and machines.</p></div>
+      <button type="button" id="refresh">Refresh</button>
+    </header>
+    <nav aria-label="Auth views">
+      <button type="button" data-view="secrets" aria-pressed="true">Secrets</button>
+      <button type="button" data-view="brains" aria-pressed="false">Brains</button>
+      <button type="button" data-view="machines" aria-pressed="false">Machines</button>
+      <button type="button" data-view="sign-in" aria-pressed="false">Sign-in &amp; audit</button>
+    </nav>
+    <section class="body" id="inventory" aria-label="Inventory">
+      <div class="tools">
+        <p id="summary" role="status"></p>
+        <label id="repo-filter-label" hidden>Repository<select id="repo-filter"></select></label>
+        <label id="search-label">Filter inventory<input type="search" id="search" autocomplete="off"></label>
+      </div>
+      <p id="problem" role="alert" hidden></p>
+      <p id="receipt" role="status" hidden></p>
+      <div class="table" id="table" role="region" aria-label="Inventory results" tabindex="0" hidden></div>
+    </section>
+    <section class="body" id="sign-in" aria-label="Sign-in and audit" hidden>
+      <dl aria-live="polite">
+        <div><dt>Registered passkeys</dt><dd id="passkeys">Checking…</dd></div>
+        <div><dt>Google sign-in configuration</dt><dd id="google">Checking…</dd></div>
+        <div><dt>Dashboard session signing</dt><dd id="session">Checking…</dd></div>
+      </dl>
+      <h2>Security baseline</h2>
+      <p id="audit-result" role="status">Check the current host configuration.</p>
+      <button type="button" id="audit">Run baseline audit</button>
+    </section>
+    <dialog id="credential-dialog" aria-labelledby="credential-heading">
+      <h2 id="credential-heading"></h2>
+      <p id="credential-key"></p>
+      <div id="credential-fields">
+        <label>Label<input id="credential-label" maxlength="120" autocomplete="off"></label>
+        <label>Repository binding<input id="credential-repo" maxlength="256" list="registered-repositories" autocomplete="off"></label>
+        <datalist id="registered-repositories"></datalist>
+        <button type="button" id="credential-clear-repo">Clear binding</button>
+        <p class="muted" id="binding-status"></p>
+        <label>Replacement value<input type="password" id="credential-value" maxlength="16384" autocomplete="new-password"></label>
+      </div>
+      <div id="delete-fields" hidden>
+        <p>Remove this credential from this host’s encrypted store. Enter its name to confirm.</p>
+        <label>Credential name<input id="credential-confirm" maxlength="256" autocomplete="off"></label>
+      </div>
+      <p id="credential-error" role="alert" hidden></p>
+      <div class="tools">
+        <button type="button" id="credential-close">Cancel</button>
+        <button type="button" id="credential-replace">Replace value</button>
+        <button type="button" id="credential-save">Save details</button>
+      </div>
+    </dialog>
+  </main>
+`;
+
+const count = value => Number.isSafeInteger(value) && value >= 0;
+const words = values => Array.isArray(values) && values.length ? values.join(', ') : 'Unbound';
+const date = value => typeof value === 'string' && Number.isFinite(Date.parse(value))
+  ? new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).format(new Date(value)) : 'Unscheduled';
+const state = (value, positive, negative) => value === true ? positive : value === false ? negative : 'Unreported';
+
+const views = {
+  secrets: {
+    name: 'credentials', headers: ['Credential', 'Provider', 'Bound repositories', 'Storage', 'Rotation'],
+    row: item => [item.label ? `${item.key} · ${item.label}` : item.key, item.provider_name || 'Unassigned', words(item.repos),
+      state(item.set, 'Stored', 'Empty'), item.rotation_overdue ? 'Overdue' : date(item.next_rotate_due)],
+  },
+  brains: {
+    name: 'brains', headers: ['Brain', 'Layer', 'Memory nodes', 'State'],
+    row: item => [item.name, item.layer, count(item.node_count) ? String(item.node_count) : 'Unreported',
+      state(item.exists, 'Present', 'Unavailable')],
+  },
+  machines: {
+    name: 'machines', headers: ['Machine', 'OS', 'Role', 'Mesh state'],
+    row: item => [item.self ? item.hostname + ' (this host)' : item.hostname, item.os || 'Unreported',
+      item.role || 'Unassigned', item.vault_only ? 'Registered' : state(item.online, 'Online', 'Offline')],
+  },
+};
+
+class AuthHome extends HTMLElement {
+  constructor() {
+    super();
+    this.activeView = 'secrets';
+    this.inventory = {};
+    this.attachShadow({ mode: 'open' }).append(template.content.cloneNode(true));
+    this.field('refresh').addEventListener('click', () => void this.load());
+    this.field('audit').addEventListener('click', () => void this.audit());
+    this.field('search').addEventListener('input', () => this.renderInventory());
+    this.field('repo-filter').addEventListener('change', () => this.renderInventory());
+    this.field('credential-close').addEventListener('click', () => this.field('credential-dialog').close());
+    this.field('credential-save').addEventListener('click', () => void this.changeCredential(this.credentialAction));
+    this.field('credential-replace').addEventListener('click', () => void this.changeCredential('replace'));
+    this.field('credential-repo').addEventListener('input', () => { this.bindingChanged = true; });
+    this.field('credential-clear-repo').addEventListener('click', () => {
+      this.bindingChanged = true;
+      this.field('credential-repo').value = '';
+      this.field('binding-status').textContent = 'The binding will be cleared when you save.';
+    });
+    this.field('credential-dialog').addEventListener('cancel', event => {
+      if (this.credentialBusy) event.preventDefault();
+    });
+    this.field('credential-dialog').addEventListener('close', () => {
+      this.field('credential-value').value = '';
+      this.field('credential-confirm').value = '';
+    });
+    for (const button of this.shadowRoot.querySelectorAll('[data-view]')) {
+      button.addEventListener('click', () => {
+        this.activeView = button.dataset.view;
+        this.field('search').value = '';
+        for (const item of this.shadowRoot.querySelectorAll('[data-view]')) {
+          item.setAttribute('aria-pressed', String(item === button));
+        }
+        this.renderInventory();
+      });
+    }
+  }
+
+  field(id) { return this.shadowRoot.getElementById(id); }
+
+  repoAliases() {
+    const groups = new Map();
+    for (const brain of this.inventory.brains?.rows || []) {
+      if (brain.layer !== 'project' || typeof brain.name !== 'string') continue;
+      const normalized = brain.name.toLowerCase().replaceAll('_', '-');
+      const labels = groups.get(normalized) || new Set();
+      labels.add(brain.name);
+      groups.set(normalized, labels);
+    }
+    return new Map([...groups].filter(([, labels]) => labels.size === 1)
+      .map(([key, labels]) => [key, [...labels][0]]));
+  }
+
+  renderInventory() {
+    const signing = this.activeView === 'sign-in';
+    this.field('sign-in').hidden = !signing;
+    this.field('inventory').hidden = signing;
+    if (signing) return;
+
+    const view = views[this.activeView];
+    const result = this.inventory[this.activeView];
+    const problem = this.field('problem');
+    const tableRegion = this.field('table');
+    const summary = this.field('summary');
+    const search = this.field('search');
+    const repoFilter = this.field('repo-filter');
+    const credentials = this.activeView === 'secrets';
+    problem.hidden = !result?.error;
+    problem.textContent = result?.error || '';
+    tableRegion.hidden = true;
+    tableRegion.replaceChildren();
+    this.field('search-label').hidden = !result?.rows?.length;
+    this.field('repo-filter-label').hidden = !credentials || !result?.rows?.length;
+    if (!result) { summary.textContent = `Loading ${view.name}…`; return; }
+    if (result.error) { summary.textContent = ''; return; }
+
+    const aliases = credentials ? this.repoAliases() : new Map();
+    const repoLabels = item => [...new Set((Array.isArray(item.repos) ? item.repos : []).filter(repo => typeof repo === 'string').map(repo =>
+      aliases.get(repo.toLowerCase().replaceAll('_', '-')) || repo))];
+    const selectedRepo = repoFilter.value;
+    if (credentials) {
+      const repos = [...new Set(result.rows.flatMap(repoLabels))].sort((left, right) => left.localeCompare(right));
+      repoFilter.replaceChildren(new Option('All repositories', ''),
+        ...repos.map(repo => new Option(repo, repo)));
+      if (repos.includes(selectedRepo)) repoFilter.value = selectedRepo;
+    }
+    const query = search.value.trim().toLocaleLowerCase();
+    const rows = result.rows.flatMap(item => {
+      const repos = credentials ? repoLabels(item) : [];
+      if (credentials && repoFilter.value && !repos.includes(repoFilter.value)) return [];
+      const values = view.row(credentials ? { ...item, repos } : item);
+      const searchText = values.concat(credentials ? item.repos || [] : []).join(' ').toLocaleLowerCase();
+      return searchText.includes(query) ? [{ item, values }] : [];
+    });
+    summary.textContent = rows.length === result.rows.length
+      ? `${result.rows.length} ${view.name}` : `${rows.length} of ${result.rows.length} ${view.name}`;
+    if (!rows.length) return;
+    const table = document.createElement('table');
+    table.setAttribute('aria-label', view.name);
+    const heading = table.createTHead().insertRow();
+    const canEdit = credentials && typeof this.host?.changeCredential === 'function';
+    for (const title of canEdit ? [...view.headers, 'Manage'] : view.headers) {
+      const cell = document.createElement('th');
+      cell.scope = 'col';
+      cell.textContent = title;
+      heading.append(cell);
+    }
+    const body = table.createTBody();
+    for (const { item, values } of rows) {
+      const entry = body.insertRow();
+      for (const value of values) {
+        const cell = entry.insertCell();
+        cell.textContent = value ?? 'Unreported';
+        if (['Stored', 'Online', 'Present'].includes(value)) cell.className = 'state-ready';
+        if (['Overdue', 'Offline', 'Empty'].includes(value)) cell.className = 'state-attention';
+      }
+      if (canEdit) {
+        const actions = entry.insertCell();
+        actions.className = 'actions';
+        for (const [action, label] of [['edit', 'Edit'], ['delete', 'Delete']]) {
+          const button = document.createElement('button');
+          button.type = 'button';
+          button.textContent = label;
+          button.setAttribute('aria-label', `${label} ${item.key}`);
+          button.addEventListener('click', () => this.openCredential(item, action));
+          actions.append(button);
+        }
+      }
+    }
+    tableRegion.append(table);
+    tableRegion.hidden = false;
+  }
+
+  openCredential(item, action) {
+    const deleting = action === 'delete';
+    this.selectedCredential = item;
+    this.credentialAction = action;
+    this.bindingChanged = false;
+    this.field('credential-heading').textContent = deleting ? 'Delete stored credential' : 'Edit credential';
+    this.field('credential-key').textContent = item.key;
+    this.field('credential-fields').hidden = deleting;
+    this.field('delete-fields').hidden = !deleting;
+    this.field('credential-replace').hidden = deleting;
+    this.field('credential-save').textContent = deleting ? 'Delete credential' : 'Save details';
+    this.field('credential-label').value = item.label || '';
+    this.field('credential-repo').value = (item.repos || []).length <= 1 ? item.repos?.[0] || '' : '';
+    this.field('registered-repositories').replaceChildren(
+      ...[...this.repoAliases().values()].sort().map(repo => new Option(repo, repo)),
+    );
+    this.field('credential-error').hidden = true;
+    this.field('binding-status').textContent = item.repos?.length > 1
+      ? `Current bindings: ${item.repos.join(', ')}. Select one repository to replace them.`
+      : '';
+    this.field('credential-dialog').showModal();
+  }
+
+  async changeCredential(action) {
+    if (this.credentialBusy || !this.selectedCredential) return;
+    const { key } = this.selectedCredential;
+    const error = this.field('credential-error');
+    const data = { action, key };
+    if (action === 'edit') {
+      data.label = this.field('credential-label').value;
+      if (this.bindingChanged) data.repo = this.field('credential-repo').value;
+    } else if (action === 'replace') {
+      data.value = this.field('credential-value').value;
+      this.field('credential-value').value = '';
+    } else {
+      data.confirm = this.field('credential-confirm').value;
+    }
+    this.credentialBusy = true;
+    const controls = ['credential-close', 'credential-save', 'credential-replace'];
+    for (const id of controls) this.field(id).disabled = true;
+    error.hidden = true;
+    try {
+      const result = await this.host.changeCredential(data);
+      if (result?.ok !== true) throw new Error('Auth did not confirm the change.');
+      this.field('credential-dialog').close();
+      const receipt = this.field('receipt');
+      receipt.textContent = action === 'delete' ? `Deleted ${key} from this host’s store.`
+        : action === 'replace' ? `Replaced the stored value for ${key}.` : `Saved details for ${key}.`;
+      receipt.hidden = false;
+      await this.load();
+    } catch (failure) {
+      error.textContent = failure.message;
+      error.hidden = false;
+    } finally {
+      this.credentialBusy = false;
+      for (const id of controls) this.field(id).disabled = false;
+    }
+  }
+
+  async load() {
+    const button = this.field('refresh');
+    if (button.disabled) return;
+    button.disabled = true;
+    this.inventory = {};
+    this.renderInventory();
+    await Promise.all([
+      ...Object.keys(views).map(async resource => {
+        try {
+          const rows = await this.host.readInventory(resource);
+          if (!Array.isArray(rows)) throw new Error('Incomplete inventory response');
+          this.inventory[resource] = { rows };
+        } catch (error) {
+          this.inventory[resource] = { error: `Could not load ${views[resource].name}. ${error.message}` };
+        }
+        this.renderInventory();
+      }),
+      this.loadSignIn(),
+    ]);
+    button.disabled = false;
+  }
+
+  async loadSignIn() {
+    for (const id of ['passkeys', 'google', 'session']) this.field(id).textContent = 'Checking…';
+    const [status, session] = await Promise.allSettled([
+      this.host?.run('status'), this.host?.run('session'),
+    ]);
+    const providers = status.status === 'fulfilled' ? status.value : null;
+    const registered = providers?.passkey?.registered_count;
+    this.field('passkeys').textContent = count(registered) ? String(registered) : 'Unavailable';
+    this.field('google').textContent = state(providers?.google_oauth2?.configured, 'Configured', 'Needs setup');
+    this.field('session').textContent = state(session.status === 'fulfilled' && session.value
+      ? session.value.session_secret_configured : null, 'Configured', 'Needs setup');
+  }
+
+  async audit() {
+    const button = this.field('audit');
+    const result = this.field('audit-result');
+    if (button.disabled) return;
+    button.disabled = true;
+    result.textContent = 'Checking this host…';
+    try {
+      let report;
+      try { report = await this.host.run('audit'); }
+      catch (error) { report = JSON.parse(error.message); }
+      if (typeof report?.passed !== 'boolean' || !count(report.findings_count)) throw new Error('Invalid audit response');
+      const findings = `${report.findings_count} ${report.findings_count === 1 ? 'finding' : 'findings'}`;
+      result.textContent = report.passed ? `Baseline passed with ${findings}.` : `Review required. ${findings}.`;
+      result.className = report.passed && !report.findings_count ? 'state-ready' : 'state-attention';
+    } catch {
+      result.textContent = 'Baseline audit unavailable. Retry or run auth audit in the terminal.';
+      result.className = 'state-attention';
+    } finally { button.disabled = false; }
+  }
+}
+
+if (!customElements.get('tr-auth-home')) customElements.define('tr-auth-home', AuthHome);

package/scaffold/.agent/skills/total-recall/plugins/automations/BRICK.md

@@ -0,0 +1,7 @@
+# Automation source collection
+
+Copy `capability/` into your application. Import `collectSources` from `./capability/index.mjs` and supply unique source IDs, an adapter map, an ISO check timestamp and an optional positive record limit.
+
+Each adapter returns records or `{records,status,error?}`. Status is `ok`, `partial`, `unsupported`, `disabled`, `error` or `unauthorized`. The collector returns `automations`, independent source `coverage`, and `checked_at`; one failed source does not erase successful evidence. Missing adapters stay unsupported and oversized inventories become partial.
+
+Your application owns authorization, data shape, adapter timeouts, execution and persistence. Supply transports and credentials directly to your own adapters. This capability performs no filesystem, network, process or environment access and prints nothing.

package/scaffold/.agent/skills/total-recall/plugins/automations/DESIGN.md

@@ -0,0 +1,53 @@
+---
+version: alpha
+name: Automation Control Ledger
+description: A dark operations ledger that keeps scheduling, source coverage and observed runs visually separate.
+colors:
+  primary: "#f2bd63"
+  background: "#181713"
+  surface: "#24221c"
+  text: "#f4efe5"
+  muted: "#c5bca9"
+  border: "#726652"
+  success: "#a8d5b0"
+  error: "#ffb5a9"
+  focus: "#b8d9ff"
+typography:
+  body: { fontFamily: "system-ui, sans-serif", fontSize: 14px, lineHeight: 1.45 }
+  label: { fontFamily: "ui-monospace, monospace", fontSize: 12px, fontWeight: 700 }
+spacing: { sm: 8px, md: 16px, touch: 44px }
+rounded: { md: 8px }
+components:
+  ledger-note:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    padding: "{spacing.md}"
+    rounded: "{rounded.md}"
+  ledger-label:
+    textColor: "{colors.primary}"
+    typography: "{typography.label}"
+---
+
+# Automations Control Ledger
+
+## Purpose and first-principles decision
+Greg checks which work is automated, where its source is available, and whether an observed run failed. He needs automation origins and coverage before interpreting counts. Replace the old chronometer card, fixed schedule chips and terminal output: they obscure these tasks and invent healthy state. Retain external element names and host.run because these are useful host contracts.
+
+The control-ledger arrangement pairs an automation index with selected automation provenance. Its branching vector mark represents one trigger feeding several owned runners; it does not imply active work. One brand, Automations, appears once. The amber accent marks selection and refresh; textual state identifies every failure or unknown. No ambient decoration or hardware imitation.
+
+## Hierarchy and screens
+The first visible line states whether inventory is unchecked, loading, complete, partial or failed, plus the last actual attempt. Refresh is the primary read action. Four purpose-defined tabs preserve the requested tasks: Scheduled (automation index, not a promise every item uses cron), Nodes (source coverage per node), Audit (observed outcomes separately from handled slots), Run (only source-advertised actions). These are domain views, not generated CLI screens. Filters cover node, source, trigger and observed state.
+
+The selected record shows trigger, enabled state, runner availability, source, placement and origin independently. Unknown values include a reason. Failed reads clear current inventory. Unsupported sources and unavailable nodes remain visible. Counts derive only from returned records and cannot imply coverage completeness.
+
+## Interaction and safety
+Read through the authenticated host bridge inside the sandbox. Load this node first and switch to mesh inventory through an explicit scope control. Reject failed wrappers and malformed inventory. A latest-request counter prevents stale refreshes overwriting newer results. Disconnect invalidates pending work; reconnect reuses its shadow root and selected tab.
+
+Every control is at least 44px, with visible focus. Tabs support arrow/Home/End navigation and maintain selected-screen state. Filters have labels; loading/errors use a live region. Layout becomes one column under 600px; text wraps safely. State change motion is a short content reveal; reduced motion removes it. Copy feedback follows actual clipboard completion. Source-advertised write controls state their target and require confirmation; arbitrary commands and credential inputs are absent.
+
+## Verification
+Use real dark host tokens, then inspect at 360, 768 and 1280px. Test unchecked/loading/partial/failed/empty states, malformed/auth-rejected requests, escaping, request races, reconnect, tab keyboard behavior and clipboard rejection. Tests use explicit fixtures; the shipped component has no fixtures or seed state. Live source authenticity is a separate backend verification obligation.
+
+## References reviewed 2026-10-29
+- [Custom element lifecycle](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
+- [Accessible tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)

package/scaffold/.agent/skills/total-recall/plugins/automations/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Iteen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scaffold/.agent/skills/total-recall/plugins/automations/README.md

@@ -0,0 +1,66 @@
+# Automations
+
+Inspect automation sources, triggers, observed outcomes and source coverage across the Total Recall mesh. Composable CLI remains the owner of reusable commands; a command definition is labelled as a manual definition until an explicit automation binding exists.
+
+```
+total-recall automations --help
+total-recall automations list --json
+total-recall automations list --local --source task-queue
+total-recall automations status --node <node>
+total-recall automations show <automation-id>
+total-recall automations cancel <local-task-id>
+total-recall automations dream --all-brains --json
+```
+
+Inventory includes plugin schedules, durable tasks, research queue work, daemon maintenance/watchers, SSSS workflow/trigger declarations, reusable composed commands, and operating-system automation declarations. macOS reads user/system launchd definitions and the current user’s crontab. Linux reads installed and loaded system/user timer units and the current user’s crontab. Commands, environment variables, queued payloads and secret values are excluded from OS summaries.
+
+Each source reports its own coverage. A missing integration, unreadable definition, denied peer, offline node or old collector remains explicit. External agent-platform automation providers have no authenticated inventory contract in this runtime and report unsupported; the plugin does not invent their state. Inventory can therefore be partial even when visible automation records are valid.
+
+A declared schedule does not prove a running scheduler. Last handled slot is not a successful run. Observed execution outcomes come from source-owned records/events; unavailable telemetry stays unknown. Individual daemon watcher registration is not reported by the current owner, so those records remain unknown even when the daemon itself is running.
+
+Selected-node tasks report `selected_node` and `placement_state`. A task without a canonical selection is `unplaced`. Peer metadata without selection evidence stays `unknown`. `last_run` includes the observed slot. `last_handled_outcome` reports the event for the exact stored handled slot. It stays unknown when no matching event exists.
+
+Full peer reads use mesh's authenticated command transport with a fixed local inventory command. If that read is unavailable, the plugin requests mesh-authenticated plugin metadata and marks coverage partial. It never sends a mesh-sync token to the PAT-protected plugin-run route.
+
+The card and panel use the same CLI contracts. Cancellation requires a pending local durable task and an owner that supports a conditional pending-to-cancelled transition. The plugin checks the saved owner state before reporting success. Older hosts can still inventory automations. Mesh peers use the plugin's local inventory operation and can report incomplete coverage. [Owner acceptance tracker](docs/projects/in-progress/ALL_AUTOMATIONS/ALL_AUTOMATIONS_PROJECT_TRACKER.md)
+
+## Scheduled plugin tasks
+
+This plugin runs the `tasks` every plugin declares in its manifest. Total Recall core has no scheduler of its own: the daemon starts this plugin's `scheduler` module through `runtime.daemon`, and it ships bundled with Total Recall.
+
+- `command` is a subcommand followed by its arguments, so `cleanup --auto --json` runs `cleanup` with `--auto --json`.
+- The timeout is the task's `timeout_ms`, else the subcommand's declared `timeout_ms`, else 60 seconds.
+- Scheduling runs against the global brain in the home folder, so run records and `plugin.task_run` events are where `list` reads them.
+- A failed run logs its reason and the end of its output, and alerts the operator through operator-alerts once per task per day.
+- A plugin switched off runs no tasks; a missed slot within the last day runs once; the first run is the first matching slot after the task is first seen.
+
+## Installation and ownership
+
+Use `total-recall plugin install <path-to-this-checkout>` for your own Total Recall workflow. Credentials belong to shared auth. The plugin id and CLI command are `automations`. The package name is `tr-plugin-automations`. The GitHub repository name and folder name change separately.
+
+For an application you ship, `total-recall plugin vendor <path-to-this-checkout>` selects the declared capability. Its `collectSources` export takes explicit source adapters and configuration. The Total Recall CLI wrapper, scheduler and platform accounts are host dependencies.
+
+## Dream and decay
+
+Automations owns one dream task at `40 3 * * *` in each node's local time. Its placement is `per-node`. Its command is `dream --all-brains`. Decay is a phase of dream. It has no separate schedule.
+
+The plugin calls `total-recall dream --all-brains --json` through `spawnSync` with no shell. It checks core's help for `--all-brains` first. Older core versions can ignore unknown flags. The operation fails before execution if core lacks the flag. It also fails for process errors, signals, invalid output and failed brain results. The JSON response reports `exit_code`, `child_exit_code` and `results`. Core must return a nonempty results array, either directly or in a `results` or `brains` field. The child timeout is 30 minutes. The host timeout is 31 minutes.
+
+`list` shows the dream task on each node. It reads the last real outcome from that node's task events. A handled slot stays separate from a real outcome. The cloud daemon must coordinate tasks across the mesh through Automations. This checkout change adds no new transport or deployment. Fleet execution requires a compatible core and an installed plugin on each node.
+
+## Development
+
+`npm test` runs only owner root/UI specs through `vitest.config.mjs`. Injected skill evaluations run independently in their owner and are not Vitest suites. Tests must use isolated/injected state and must not cancel real tasks. Plugin state is derived; persistent source state and controls stay with their owning APIs.
+
+## Using this from an agent
+
+Send questions about what is scheduled here: tasks, triggers and real outcomes across the mesh. A declared schedule does not prove anything ran, so read the outcome. To create a reusable command, use Composable CLI.
+
+```bash
+total-recall automations list --json
+total-recall automations status --node <node>
+total-recall automations show <automation-id>
+total-recall automations cancel <local-task-id>
+```
+
+Raw commands this plugin owns: `crontab -l` and `launchctl list`.