toga-ai 1.0.168 → 1.0.170

package/knowledge/CONVENTIONS.md

@@ -34,10 +34,12 @@ knowledge/
 │   └── standards/*.md     # 2.0 coding standards (_underscore)
 ├── standalone/
 │   └── apps/<repo>/architecture.md + features/*.md  # non-PHP apps (e.g. togatech); no core
-└── clients/<client>/
-    ├── profile.md
-    ├── features/*.md      # client-specific feature overrides (link back to apps/)
-    └── workflows/*.md     # client business processes
+├── clients/<client>/
+│   ├── profile.md
+│   ├── features/*.md      # client-specific feature overrides (link back to apps/)
+│   └── workflows/*.md     # client business processes
+└── sessions/              # team-shared resumable sessions (NOT knowledge docs)
+    └── YYYY-MM-DD-<slug>-<author>.md
 ```
 
 **App folders are keyed by REPO name** (`worker2`, `_underscore`, `api2`, `library`),
@@ -211,6 +213,39 @@ Never hand-edited. `node knowledge.js index` regenerates the master `INDEX.md`,
 `<fw>/apps/<repo>/INDEX.md`, and each `clients/<client>/INDEX.md` from frontmatter, so
 they can never drift from the docs.
 
+## Team-shared sessions (`knowledge/sessions/`, `type: session`)
+
+Sessions are **resumable work state**, not knowledge docs — they let one developer save an
+in-progress task and another (or future-you, on another machine) resume it. They ride the
+same git rails as `capture` (rebase-before-push to `_main`), but are managed by the
+`session-save` / `session-resume` skills and the `knowledge.js session-*` commands, **not**
+by `capture`.
+
+- **File:** `knowledge/sessions/YYYY-MM-DD-<slug>-<author>.md`. The `<author>` suffix lets
+  two developers reuse a slug without collision.
+- **Frontmatter** (its own schema — distinct from the doc frontmatter above):
+  ```yaml
+  type: session
+  slug: <kebab-slug>
+  title: <short human title>
+  author: <kb-username>
+  repos: [<repo>, …]      # repos touched (free-form; NOT checked against registry)
+  framework: "1.0" | "2.0" | "both" | "standalone"
+  client: <slug> | shared
+  status: active | stale  # stale = abandoned / safe to delete
+  created: YYYY-MM-DD
+  updated: YYYY-MM-DD
+  ```
+- **Not validated as docs.** `allDocs()` walks only `1.0/`, `2.0/`, `standalone/`, and
+  `clients/`, so `validate` and `index` deliberately ignore `sessions/`. `session-save`
+  runs its own lightweight frontmatter check and the **same secret scan** before pushing —
+  never paste credentials into a session body.
+- **Commands:** `session-save --file=`, `session-list [--stale=N --mine --json]`,
+  `session-show <id>`, `session-delete <id>`. List/show/delete read from `origin/_main` after
+  a `git fetch`, so they reflect the freshest team state without touching the working tree.
+- **Cleanup is manual.** `session-list` flags sessions older than 14 days as `STALE`;
+  developers retire them with `/session-resume delete <id>` (no auto-deletion).
+
 ## Integrity
 
 `node knowledge.js validate` runs after every `capture` write and enforces:

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
-- **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 1 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -4,4 +4,5 @@
 |-----|-----------|---------|-------|
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
+| [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/service-card-entitlements.md

@@ -0,0 +1,103 @@
+---
+title: "Service Card Entitlement Display"
+framework: "2.0"
+repo: toga2-view
+project: TOGa View
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: ["bala"]
+files:
+  - src/components/ServiceCard/ServiceCard.tsx
+  - src/components/ServiceCard/index.ts
+  - src/hooks/useBundleServices.ts
+  - src/pages/Home/api/homeApi.ts
+  - src/pages/Home/view/HomePage.tsx
+  - src/pages/Home/viewModels/useHomePageViewModel.ts
+  - src/pages/Services/view/ServicesPage.tsx
+  - src/pages/Services/viewModels/useServicePageViewModel.ts
+related:
+  - clients/rate/profile.md
+---
+
+## Summary
+
+Rate's home and services pages display one service card per purchased entitlement. The card
+shows a hero image, title, Active badge, contract number, plan, price (or address for warranty
+cards), renewal date, and a Manage button. Previously the UI showed one card per bundle type
+regardless of how many entitlements the user had purchased.
+
+## Key files / entry points
+
+- `ServiceCard.tsx` — the card component; accepts `serviceType` to switch the second data row
+  between Price (tech) and Address (warranty)
+- `useBundleServices.ts` — shared hook returning one `BundleService` per active entitlement;
+  used by both `useHomePageViewModel` and `useServicePageViewModel`
+- `homeApi.ts` — `getActiveServices()` fetches entitlements with subscription and address fields
+- `HomePage.tsx` — shows max 3 cards; "View All Services" tertiary text button links to `/services`
+- `ServicesPage.tsx` — shows all entitlements in a 2-column grid, scrollable
+
+## How it works
+
+1. `getActiveServices(borrowerId)` queries `Entitlements` with:
+   - INNER JOIN: `Contacts`, `Customers`, `Subscriptions`
+   - LEFT JOIN (`ojoin`): `ContactAddresses`, `Addresses` — keeps entitlements whose contact
+     has no address instead of dropping the row
+   - Fields: `uuid`, `number`, `saleItem.title/uuid`, `subscription.isActive/amount/frequency/dateEnd`,
+     `contact.primaryContactAddress.address.line1`
+
+2. `useBundleServices` filters `subscription.isActive === true` and builds one `BundleService`
+   per entitlement. It also fetches bundles to resolve `bundleUuid` for navigation.
+
+3. `detectServiceType(title)` classifies each card:
+   - `'warranty'` — title includes "warranty" or "whole home" (and NOT "tech")
+   - `'tech'` — title includes "tech" or "support"
+   - `'other'` — everything else
+
+4. `ServiceCard` renders the data rows based on `serviceType`:
+   - Tech / other → row 2: **Price** (`$XX.XX`)
+   - Warranty → row 2: **Address** (`contact.primaryContactAddress.address.line1`)
+
+5. Home page slices `allServices` to 3 (`HOME_SERVICE_LIMIT`). If more exist, a tertiary
+   "View All Services" text link appears below the cards pointing to `/services`.
+
+6. Services page renders all entitlements with no cap in a `grid-cols-1 md:grid-cols-2` grid.
+
+## Data model
+
+Address path in DB:
+```
+Entitlements.contactId
+  → Contacts.primaryContactAddressId
+  → ContactAddresses.id → ContactAddresses.addressId
+  → Addresses.line1
+```
+
+Contract number comes from `Entitlements.number` (auto-incremented with ET prefix, e.g. `ET100017`).
+
+## Client variations
+
+This feature is Rate-specific. The warranty card showing Address instead of Price is driven
+by Rate's product mix (Whole Home Warranty + Tech Support). Other clients with different
+product types would need `detectServiceType` extended or overridden.
+
+## Gotchas / known issues
+
+- **`ojoin` is required for address** — using INNER JOIN (`join`) drops every entitlement
+  whose contact has no `primaryContactAddressId`, silently hiding those cards.
+- **`T00:00:00` in date formatting** — `formatDate` appends this before parsing to avoid
+  timezone offset shifting the renewal date back by one day.
+- **Per-entitlement, not per-bundle** — `useBundleServices` intentionally does not dedup.
+  A user with 8 entitlements of the same product sees 8 cards. The old dedup-by-bundle
+  behavior (1 card per service type) was the previous design.
+- **Inactive bundles are not shown** — the new design only renders active entitlements.
+  The "Add a subscription" dashed button (handled by `useAddSubscription` hook +
+  `AddSubscriptionSheet`) replaces the old "Get Started" inactive bundle cards.
+- **`useBundleServices` is shared** — both `useHomePageViewModel` and `useServicePageViewModel`
+  call it. Changes to the hook affect both pages.
+
+## Change history
+
+- 2026-06-23 — Initial implementation: per-entitlement card display, new ServiceCard component,
+  address via LEFT JOIN, 3-card home limit with View All Services tertiary button (bala)

package/knowledge.js

@@ -21,6 +21,11 @@
  *   manifest
  *   kickoff-preflight --repos=a,b,c --client=<slug> --layer=<...> --q=<...>
  *   publish           --msg= --mirror= --branch=
+ *   session-save      --file=<path> --msg= --branch=
+ *   session-list      --stale=<days> --mine[=<author>] --json --branch=
+ *   session-show      <id> --branch=
+ *   session-delete    <id> --msg= --branch=
+ *   skills            --installed=<.claude/skills dir> --json
  */
 
 'use strict';
@@ -723,6 +728,221 @@ function cmdValidate() {
     else console.log('validate: FAILED — see errors above');
 }
 
+/* ------------------------------------------------------------------ */
+/* team-shared sessions — knowledge/sessions/<id>.md ride the same git  */
+/* rails as publish (rebase-before-push to _main). allDocs() does NOT    */
+/* walk sessions/, so validate/index ignore them; session-save runs its  */
+/* own lightweight frontmatter + secret check below.                     */
+/* ------------------------------------------------------------------ */
+
+const SESSIONS_DIR = path.join(ROOT, 'sessions');
+const SESSION_REQUIRED = ['type', 'slug', 'title', 'author', 'status', 'created', 'updated'];
+
+function gitRun(cmd, timeout) {
+    const opts = { cwd: __dirname, encoding: 'utf8', stdio: 'pipe' };
+    if (timeout) opts.timeout = timeout;
+    return require('child_process').execSync(cmd, opts);
+}
+
+function isGitClone() {
+    try { gitRun('git rev-parse --git-dir'); return true; } catch { return false; }
+}
+
+function currentAuthor() {
+    try { return gitRun('git config user.name').trim(); } catch { return ''; }
+}
+
+/* commit whatever is already staged, then rebase-before-push (3x retry  */
+/* for the CI version-bump race). Caller stages via git add / git rm.    */
+/* Returns a bare status token; callers map it to a SESSION:/SKILLS: line.*/
+function pushStaged(opts) {
+    const branch = (opts && opts.branch) || '_main';
+    const restrict = opts && opts.restrictPrefix;
+    const staged = gitRun('git diff --cached --name-only').split('\n').map(s => s.trim()).filter(Boolean);
+    if (!staged.length) return 'NO_CHANGES';
+    if (restrict) {
+        const outside = staged.filter(f => !f.startsWith(restrict));
+        if (outside.length) { gitRun('git reset -q'); return 'ABORT_OUTSIDE:' + outside.join(', '); }
+    }
+    const msg = String((opts && opts.msg) || 'sessions: update').replace(/["\\]/g, "'").slice(0, 200);
+    gitRun(`git commit -m "${msg}"`);
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+            gitRun('git fetch origin');
+            gitRun(`git rebase origin/${branch}`);
+            gitRun(`git push origin HEAD:${branch}`);
+            return 'PUSHED';
+        } catch (e) {
+            let status = '';
+            try { status = gitRun('git status --porcelain'); } catch { /* ignore */ }
+            if (/^(UU|AA|DD|AU|UA|DU|UD) /m.test(status)) {
+                try { gitRun('git rebase --abort'); } catch { /* ignore */ }
+                return 'CONFLICT';
+            }
+            // else: almost certainly a fresh CI bump (non-fast-forward) — retry
+        }
+    }
+    return 'PUSH_FAILED';
+}
+
+function reportSession(status, branch) {
+    const br = branch || '_main';
+    if (status === 'PUSHED') { console.log(`SESSION: PUSHED to ${br} — teammates see it on the next /session-resume (git fetch)`); return; }
+    if (status === 'DELETED') { console.log(`SESSION: DELETED from ${br}`); return; }
+    if (status === 'NO_CHANGES') { console.log('SESSION: NO_CHANGES — nothing new to push'); return; }
+    if (status === 'CONFLICT') { console.log(`SESSION: CONFLICT — rebase onto origin/${br} hit a real conflict; resolve manually, then retry`); process.exitCode = 1; return; }
+    if (status && status.startsWith('ABORT_OUTSIDE')) { console.log('SESSION: ABORT_OUTSIDE_SESSIONS — refusing to commit non-session files: ' + status.slice('ABORT_OUTSIDE:'.length)); process.exitCode = 1; return; }
+    console.log(`SESSION: PUSH_FAILED after 3 attempts — run manually: git -C "${__dirname}" push origin HEAD:${br}`); process.exitCode = 1;
+}
+
+function fetchQuiet() {
+    try { gitRun('git fetch origin', 6000); return true; } catch { return false; }
+}
+
+/* List session files from origin/<branch> WITHOUT touching the working  */
+/* tree (so a teammate's just-pushed session shows up after a fetch even  */
+/* if it isn't checked out locally). Falls back to the working tree.      */
+function listSessionDocs(branch, doFetch) {
+    const br = branch || '_main';
+    if (isGitClone()) {
+        if (doFetch) fetchQuiet();
+        let names = null;
+        try { names = gitRun(`git ls-tree -r --name-only origin/${br} knowledge/sessions/`).split('\n').map(s => s.trim()).filter(f => f.endsWith('.md')); }
+        catch { names = null; }
+        if (names && names.length) {
+            const out = [];
+            for (const rel of names) {
+                try { out.push({ id: path.basename(rel, '.md'), rel, content: gitRun(`git show origin/${br}:${rel}`) }); } catch { /* skip */ }
+            }
+            if (out.length) return out;
+        }
+    }
+    // fallback: local working tree
+    if (!fs.existsSync(SESSIONS_DIR)) return [];
+    return fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.md')).map(f => ({
+        id: path.basename(f, '.md'), rel: 'knowledge/sessions/' + f, content: fs.readFileSync(path.join(SESSIONS_DIR, f), 'utf8'),
+    }));
+}
+
+function ageDays(dateStr) {
+    const m = String(dateStr || '').match(/(\d{4})-(\d{2})-(\d{2})/);
+    if (!m) return null;
+    const d = Date.UTC(+m[1], +m[2] - 1, +m[3]);
+    const now = new Date();
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    return Math.round((today - d) / 86400000);
+}
+
+function padTo(s, n) { s = String(s); return s.length >= n ? s : s + ' '.repeat(n - s.length); }
+function clip(s, n) { s = String(s).replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; }
+
+function cmdSessionSave(args) {
+    const file = args.file;
+    if (!file) return fail('session-save requires --file=<path>');
+    const abs = path.resolve(String(file));
+    if (abs !== path.join(SESSIONS_DIR, path.basename(abs)) && !abs.startsWith(SESSIONS_DIR + path.sep)) {
+        console.log('SESSION: ABORT_OUTSIDE_SESSIONS — file must live under knowledge/sessions/'); process.exitCode = 1; return;
+    }
+    if (!fs.existsSync(abs)) return fail('session file not found: ' + abs);
+    const content = fs.readFileSync(abs, 'utf8');
+    const { data } = parseFrontmatter(content);
+    const missing = SESSION_REQUIRED.filter(k => !data[k]);
+    if (missing.length) { console.log('SESSION: INVALID — missing frontmatter: ' + missing.join(', ')); process.exitCode = 1; return; }
+    if (data.type !== 'session') { console.log('SESSION: INVALID — type must be "session"'); process.exitCode = 1; return; }
+    if (!['active', 'stale'].includes(data.status)) { console.log('SESSION: INVALID — status must be active|stale'); process.exitCode = 1; return; }
+    const secrets = scanSecrets(content);
+    if (secrets.length) { console.log('SESSION: SECRET — ' + secrets.map(s => `line ${s.line}: ${s.reason}`).join('; ') + '; redact before saving'); process.exitCode = 1; return; }
+    if (!isGitClone()) { console.log('SESSION: NOT_GIT — session written locally only; run `npx toga-ai` to create a pushable clone'); return; }
+    const rel = 'knowledge/sessions/' + path.basename(abs);
+    gitRun(`git add "${rel}"`);
+    reportSession(pushStaged({ msg: args.msg || ('session: ' + data.slug), branch: args.branch, restrictPrefix: 'knowledge/sessions/' }), args.branch);
+}
+
+function cmdSessionList(args) {
+    const rows = listSessionDocs(args.branch, true).map(e => {
+        const { data } = parseFrontmatter(e.content);
+        const updated = data.updated || data.created || '';
+        const age = ageDays(updated);
+        return {
+            id: e.id, date: updated, author: data.author || '', framework: data.framework || '',
+            repos: Array.isArray(data.repos) ? data.repos.join(' ') : (data.repos || ''),
+            client: data.client || '', title: data.title || '', age,
+        };
+    });
+    const staleDays = args.stale !== undefined && args.stale !== true ? parseInt(args.stale, 10) : 14;
+    const mine = args.mine ? (typeof args.mine === 'string' ? args.mine : currentAuthor()) : null;
+    const enriched = rows
+        .map(r => ({ ...r, stale: (Number.isInteger(staleDays) && r.age !== null && r.age > staleDays) }))
+        .filter(r => !mine || r.author === mine)
+        .sort((a, b) => String(b.date).localeCompare(String(a.date)));
+    if (args.json) { console.log(JSON.stringify(enriched)); return; }
+    if (!enriched.length) { console.log('No team sessions saved yet.'); return; }
+    console.log(padTo('', 6) + ' ' + padTo('DATE', 10) + ' ' + padTo('AUTHOR', 12) + ' ' + padTo('AGE', 5) + ' ' + padTo('ID', 40) + ' TASK');
+    for (const r of enriched) {
+        console.log(
+            padTo(r.stale ? 'STALE' : 'ok', 6) + ' ' + padTo(r.date, 10) + ' ' + padTo(clip(r.author, 12), 12) + ' ' +
+            padTo((r.age === null ? '?' : r.age + 'd'), 5) + ' ' + padTo(clip(r.id, 40), 40) + ' ' + clip(r.title, 60)
+        );
+    }
+}
+
+function cmdSessionShow(args) {
+    const id = args.id || (args._ && args._[0]);
+    if (!id) return fail('session-show requires an id (filename without .md)');
+    const match = listSessionDocs(args.branch, true).find(e => e.id === id || e.id.includes(String(id)));
+    if (!match) { console.log('SESSION: NOT_FOUND — no session matching "' + id + '" (try: session-list)'); process.exitCode = 1; return; }
+    process.stdout.write(match.content);
+}
+
+function cmdSessionDelete(args) {
+    const id = args.id || (args._ && args._[0]);
+    if (!id) return fail('session-delete requires an id');
+    if (!isGitClone()) { console.log('SESSION: NOT_GIT — cannot delete a team session without a git clone'); process.exitCode = 1; return; }
+    const br = args.branch || '_main';
+    fetchQuiet();
+    const rel = 'knowledge/sessions/' + id + '.md';
+    // make sure the file is present in the working tree so git rm can stage its removal
+    try { gitRun(`git checkout origin/${br} -- "${rel}"`); } catch { /* may already be local or absent */ }
+    if (!fs.existsSync(path.join(__dirname, rel))) { console.log('SESSION: NOT_FOUND — no session "' + id + '" on origin/' + br); process.exitCode = 1; return; }
+    gitRun(`git rm -q "${rel}"`);
+    const st = pushStaged({ msg: args.msg || ('session: delete ' + id), branch: br, restrictPrefix: 'knowledge/sessions/' });
+    reportSession(st === 'PUSHED' ? 'DELETED' : st, br);
+}
+
+/* ------------------------------------------------------------------ */
+/* command: skills — generated, always-current listing of team skills  */
+/* (the README table drifts; skills frontmatter is the source of truth).*/
+/* --installed=<.claude/skills dir> marks installed/available/local-only.*/
+/* ------------------------------------------------------------------ */
+
+function cmdSkills(args) {
+    const skillsSrc = path.join(__dirname, 'skills');
+    const teamSkills = fs.existsSync(skillsSrc)
+        ? fs.readdirSync(skillsSrc, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [];
+    const meta = {};
+    for (const s of teamSkills) {
+        const skf = path.join(skillsSrc, s, 'SKILL.md');
+        let name = s, desc = '';
+        if (fs.existsSync(skf)) { const { data } = parseFrontmatter(fs.readFileSync(skf, 'utf8')); name = data.name || s; desc = data.description || ''; }
+        meta[s] = { name, desc };
+    }
+    let installed = null;
+    if (args.installed && typeof args.installed === 'string') {
+        const dir = path.resolve(args.installed);
+        installed = fs.existsSync(dir) ? fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [];
+    }
+    const rows = teamSkills.map(s => ({
+        skill: s, name: meta[s].name, description: meta[s].desc,
+        status: installed ? (installed.includes(s) ? 'installed' : 'available') : 'team',
+    }));
+    if (installed) for (const s of installed) if (!teamSkills.includes(s)) rows.push({ skill: s, name: s, description: '(local only — not in team repo)', status: 'local-only' });
+    rows.sort((a, b) => a.skill.localeCompare(b.skill));
+    if (args.json) { console.log(JSON.stringify(rows)); return; }
+    console.log(padTo('STATUS', 11) + ' ' + padTo('SKILL', 22) + ' DESCRIPTION');
+    for (const r of rows) console.log(padTo(r.status, 11) + ' ' + padTo(clip(r.skill, 22), 22) + ' ' + clip(r.description, 90));
+    if (installed && rows.some(r => r.status === 'available')) console.log('\nRun /sync-team-skills to install the "available" skills.');
+}
+
 /* ------------------------------------------------------------------ */
 /* dispatch                                                            */
 /* ------------------------------------------------------------------ */
@@ -730,6 +950,7 @@ function cmdValidate() {
 function main() {
     const [, , cmd, ...rest] = process.argv;
     const args = parseArgs(rest);
+    args._ = rest.filter(a => !a.startsWith('--'));
     switch (cmd) {
         case 'search': return cmdSearch(args);
         case 'index': return cmdIndex();
@@ -738,8 +959,13 @@ function main() {
         case 'manifest': return cmdManifest();
         case 'kickoff-preflight': return cmdPreflight(args);
         case 'publish': return cmdPublish(args);
+        case 'session-save': return cmdSessionSave(args);
+        case 'session-list': return cmdSessionList(args);
+        case 'session-show': return cmdSessionShow(args);
+        case 'session-delete': return cmdSessionDelete(args);
+        case 'skills': return cmdSkills(args);
         default:
-            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|kickoff-preflight|publish> [--flags]');
+            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|kickoff-preflight|publish|session-save|session-list|session-show|session-delete|skills> [--flags]');
             process.exitCode = 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.168",
+  "version": "1.0.170",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/scripts/hooks/session-start.js

@@ -24,6 +24,32 @@ function checkUnfinishedSession(cwd) {
     return fs.existsSync(sessionFile);
 }
 
+// Resolve the team `claude` repo (same order kickoff uses), or null.
+function resolveTeamRepo() {
+    const candidates = [];
+    if (process.env.CLAUDE_TEAM_REPO) candidates.push(process.env.CLAUDE_TEAM_REPO);
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    if (home) candidates.push(path.join(home, 'toga-tech'), path.join(home, 'claude'));
+    for (const dir of candidates) {
+        try { if (dir && fs.existsSync(path.join(dir, 'knowledge', 'registry.json'))) return dir; } catch { /* ignore */ }
+    }
+    return null;
+}
+
+// Best-effort, time-boxed peek at team sessions. Never throws; returns [] on any
+// failure (offline, no clone, slow fetch) so startup stays fast and quiet.
+function teamSessions(teamRepo) {
+    if (!teamRepo) return [];
+    try {
+        const out = require('child_process').execSync(
+            'node "' + path.join(teamRepo, 'knowledge.js') + '" session-list --json',
+            { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3500 }
+        );
+        const rows = JSON.parse(out);
+        return Array.isArray(rows) ? rows : [];
+    } catch { return []; }
+}
+
 function main() {
     const cwd = process.cwd();
     const now = new Date().toLocaleDateString('en-US', {
@@ -48,6 +74,18 @@ function main() {
         console.log('');
     }
 
+    // Surface team-shared sessions (best-effort, time-boxed — never blocks startup).
+    const teamRepo = resolveTeamRepo();
+    const sessions = teamSessions(teamRepo);
+    if (sessions.length) {
+        const newest = sessions[0];
+        const fresh = sessions.filter(s => !s.stale).length;
+        console.log(`${sessions.length} team session(s) available${fresh < sessions.length ? ` (${sessions.length - fresh} stale)` : ''}.`);
+        console.log(`  Newest: ${newest.id} by ${newest.author || 'unknown'} — "${newest.title || ''}"`);
+        console.log('  Run /session-resume <id> to continue one, or /session-resume list to see all.');
+        console.log('');
+    }
+
     console.log('Ready. Run /kickoff to prime context for your work session.');
     console.log('');
 

package/skills/session-resume/SKILL.md

@@ -9,55 +9,70 @@ You are restoring context from a prior session so that work can continue without
 information loss. The briefing you provide must be actionable and explicit about what
 NOT to do — failed approaches from prior sessions are as important as what worked.
 
+Sessions are **shared across the team**: they live in the team `claude` repo under
+`knowledge/sessions/` and are pulled fresh on every resume, so you can pick up a session a
+teammate saved (not just your own).
+
 ## Arguments
 
 ```
-/session-resume [name | "latest"]
+/session-resume [latest | <slug-or-id> | list | delete <id>]
 ```
 
-- `name` — the exact session name slug (e.g. `auth-refactor`). Matches against the
-  filename: `~/.claude/session-data/*-<name>-session.md`.
-- `latest` — loads the most recently created session file (newest by filename date).
-- If omitted, list available sessions and ask the developer which to load.
-
----
+- `latest` — load the most recently updated team session.
+- `<slug-or-id>` — load by slug (e.g. `auth-refactor`) or full id
+  (`2026-06-08-auth-refactor-asmith`).
+- `list` — show all team sessions (with author + age + stale flags) and stop.
+- `delete <id>` — remove a stale team session (confirm first), then stop.
+- If omitted, list and ask which to load.
 
-## Step 1 — Discover available sessions
+First resolve `TEAM_REPO` exactly as `kickoff`/`session-save` do (the `team-repo-path`
+memory, else `$CLAUDE_TEAM_REPO`, else probe `~/toga-tech` … for `knowledge/registry.json`).
+All commands below run `node "<TEAM_REPO>/knowledge.js" …`, which **git-fetches first** so
+teammates' just-pushed sessions are visible.
 
-Read the `~/.claude/session-data/` directory. If it does not exist or is empty:
+---
 
-```
-No saved sessions found in ~/.claude/session-data/
+## Step 1 — Discover available sessions (always fetches latest)
 
-To save a session at the end of your current work: /session-save [name]
+```bash
+node "<TEAM_REPO>/knowledge.js" session-list
 ```
 
-Then stop.
-
-Otherwise, list sessions sorted **newest first** (by the `YYYY-MM-DD` prefix):
+This prints a table (`STATUS DATE AUTHOR AGE ID TASK`), newest first, flagging sessions
+older than 14 days as `STALE`. Add `--mine=<author>` to filter to your own, `--stale=<days>`
+to change the threshold. If it prints "No team sessions saved yet.", say so and stop:
 
 ```
-Available sessions (newest first):
-  1. 2026-06-08 — auth-refactor        ~/.claude/session-data/2026-06-08-auth-refactor-session.md
-  2. 2026-06-07 — worker-cron-fix      ~/.claude/session-data/2026-06-07-worker-cron-fix-session.md
-  3. 2026-06-05 — api2-pagination      ~/.claude/session-data/2026-06-05-api2-pagination-session.md
+No team sessions saved yet. Save one at the end of your work: /session-save [name]
 ```
 
+**`list` mode:** render this table and stop here.
+
+**`delete <id>` mode:** confirm with the developer, then run
+`node "<TEAM_REPO>/knowledge.js" session-delete <id> --msg="session: retire <id>"`,
+report the `SESSION: DELETED|NOT_FOUND|CONFLICT` result, and stop.
+
 ---
 
 ## Step 2 — Resolve which session to load
 
-- If `latest` was specified, take the newest file.
-- If a name was specified, find the file whose filename contains that name slug.
-  - If multiple files match, take the newest.
-  - If none match, say: "No session found matching '<name>'. Available: [list names]."
-- If no argument was given, ask: "Which session should I load? (Enter a number or name)"
+- `latest` → the top row (newest `updated`).
+- `<slug-or-id>` → the row whose id equals it or contains the slug. If several match
+  (same slug, different authors/dates), show those candidates (date + author) and ask which.
+- If none match: "No session found matching '<x>'. Available: [list ids]."
+- No argument → ask: "Which session should I load? (id or slug)"
 
 ---
 
 ## Step 3 — Load and parse the session file
 
-Read the session file. Parse these sections:
+```bash
+node "<TEAM_REPO>/knowledge.js" session-show <id>
+```
+
+This prints the full session file (frontmatter + body) from the freshest team state.
+Parse these sections from the body:
 - **Task** — the one-sentence summary
 - **Project/Repo** — repo and framework
 - **Date** — when it was saved
@@ -77,8 +92,8 @@ Output a structured briefing in this exact format:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Session Resume: <name>
-Saved: <YYYY-MM-DD> | Repo: <repo> (<framework>)
+Session Resume: <slug>
+Saved by <author> on <YYYY-MM-DD> | Repo: <repo> (<framework>)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 TASK
@@ -153,4 +168,8 @@ model accordingly.
 - If the "Exact next step" section is blank or unclear, ask the developer what they
   want to tackle before proceeding.
 - Recommend running `/session-save` again at the end of this session to update the
-  record with new progress.
+  team record with new progress (re-saving the same slug overwrites and re-pushes it).
+- You may be resuming a **teammate's** session — the briefing header names the author.
+  When you re-save, it saves under *your* author id, leaving theirs intact.
+- Stale sessions accumulate: when `session-list` flags old ones you recognize as done,
+  retire them with `/session-resume delete <id>`.

package/skills/session-save/SKILL.md

@@ -67,30 +67,53 @@ when they resume — no thinking required.
 
 ---
 
-## Step 2 — Determine save path and filename
+## Step 2 — Resolve the team repo, author, and save path
+
+Sessions are **shared with the whole team by default** — saved into the team `claude`
+repo and pushed, so any teammate can resume them (mirrors how `capture` publishes).
+
+1. **Team repo** — resolve `TEAM_REPO` the same way `kickoff` does: the `team-repo-path`
+   Claude memory first, else `$CLAUDE_TEAM_REPO`, else auto-probe (`~/toga-tech`, …) for a
+   dir containing `knowledge/registry.json`. Persist a `team-repo-path` memory if you had
+   to discover it.
+2. **Author** — the `author-username` Claude memory (the developer's KB username, e.g.
+   `jcardinal`). If absent, fall back to `git config user.name`.
+3. **Slug** — the Step 0 name (or a derived kebab-case slug, max 4 words).
 
 ```
-File: ~/.claude/session-data/YYYY-MM-DD-<name>-session.md
-Also: <project-root>/.session-latest.md  (gitignored, for quick local reference)
+Team file: <TEAM_REPO>/knowledge/sessions/YYYY-MM-DD-<slug>-<author>.md
 ```
 
-Where:
-- `YYYY-MM-DD` = today's date (use the current date from the session)
-- `<name>` = the session name from Step 0
-- `<project-root>` = the root of the project being worked on (use the `team-repo-path`
-  memory or the current working directory; do not guess if unknown)
+The `<author>` suffix lets two developers use the same slug without collision.
+`YYYY-MM-DD` is today's date. Create `<TEAM_REPO>/knowledge/sessions/` if it does not exist.
 
-Create `~/.claude/session-data/` if it does not exist.
+**No git clone / TEAM_REPO unresolved →** fall back to the legacy local-only path
+`~/.claude/session-data/YYYY-MM-DD-<slug>-session.md` (create the dir if needed), warn the
+developer that the session was saved **locally only** (no team push possible without a
+clone — `npx toga-ai` creates one), and skip Step 4.
 
 ---
 
-## Step 3 — Write the session file
+## Step 3 — Write the session file (frontmatter + body)
 
-Write the file at both paths using this exact template. Do not reformat, summarize,
-or condense — write the full content at both locations.
+Write the team file using this exact template — **frontmatter first**, then the unchanged
+9-section body. Do not reformat, summarize, or condense.
 
 ```markdown
-# Session: <name>
+---
+type: session
+slug: <slug>
+title: <short human title from 1a>
+author: <author>
+repos: [<repo>, <repo>]        # repos touched this session
+framework: "1.0" | "2.0" | "both" | "standalone"
+client: <client-slug> | shared
+status: active                 # set to "stale" later if abandoned
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Session: <slug>
 **Date:** YYYY-MM-DD
 **Project/Repo:** <repo> (<framework>)
 **Task:** <one-sentence summary from 1a>
@@ -126,17 +149,39 @@ or condense — write the full content at both locations.
 _Saved by /session-save on YYYY-MM-DD_
 ```
 
+> **Never paste credentials into the body** (tokens, keys, passwords). The publisher
+> secret-scans the file and refuses to push if it finds one. Reference the config/constant
+> location instead.
+
 ---
 
-## Step 4 — Confirm to developer
+## Step 4 — Push to the team (skip if Step 2 fell back to local-only)
+
+Run the deterministic publisher — it validates the session frontmatter, secret-scans, and
+does the rebase-before-push to `_main` (3× retry for the CI version-bump race), staging
+**only** the session file:
+
+```bash
+node "<TEAM_REPO>/knowledge.js" session-save --file="<the team file path>" --msg="session: <slug> — <task>"
+```
+
+Read the single `SESSION:` line and act:
+- `PUSHED to _main` — done.
+- `NO_CHANGES` — file identical to what's already pushed; nothing to do.
+- `INVALID …` / `SECRET …` — fix the frontmatter / redact the value, then re-run.
+- `CONFLICT` — a real merge conflict; resolve manually in `<TEAM_REPO>`, then re-run.
+- `NOT_GIT` — no clone; the file is saved locally only (treat as the Step 2 fallback).
+- `PUSH_FAILED` — after 3 retries; run the manual push command it prints.
+
+---
 
-After writing both files, confirm:
+## Step 5 — Confirm to developer
 
 ```
-✓ Session saved: ~/.claude/session-data/YYYY-MM-DD-<name>-session.md
-✓ Latest copy:   <project-root>/.session-latest.md
+✓ Session saved to team: knowledge/sessions/YYYY-MM-DD-<slug>-<author>.md  (pushed to _main)
 
-To resume: /session-resume <name>   (or: /session-resume latest)
+To resume (from any machine): /session-resume <slug>   (or: /session-resume latest)
+See all team sessions:        /session-resume list
 
 Session captured:
   • What worked: <N items>
@@ -144,15 +189,16 @@ Session captured:
   • Next step: <exact next step summary>
 ```
 
-If either write fails, report the error with the full path that failed and the reason.
+If the save fell back to local-only, say so plainly and give the local path instead.
 
 ---
 
 ## Notes
 
-- Both files must be written. If the project root cannot be determined, write
-  only to `~/.claude/session-data/` and note that the local copy was skipped.
-- The `.session-latest.md` file is gitignored (see `.gitignore`). It exists for
-  quick local reference when the developer returns to the project the next day.
-- Do NOT compress or summarize the "What did NOT work" section. Future sessions
-  depend on exact failure reasons to avoid repeating dead ends.
+- **Team-by-default.** The whole point is cross-developer handoff: one dev saves, another
+  resumes. Local-only is just the offline/no-clone fallback.
+- Do NOT compress or summarize the "What did NOT work" section. Future sessions depend on
+  exact failure reasons to avoid repeating dead ends.
+- The session file lives under `knowledge/sessions/`, which `knowledge.js validate`/`index`
+  deliberately ignore — sessions are not knowledge docs and have their own listing
+  (`/session-resume list`).

package/skills/team-skills/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: team-skills
+description: Lists every skill available in the team `claude` knowledge repo with its description, and marks which are installed in this project, available to pull, or local-only. Use when the developer says "what skills are available", "list team skills", "team skills", "show skills", "what can you do", or asks which team skills exist. Pairs with /sync-team-skills, which installs them.
+---
+
+# Team Skills — discover what the team knowledge base offers
+
+`/sync-team-skills` *installs* skills but there's no way to *see* what exists first. This
+skill renders an always-current listing straight from each skill's `SKILL.md` frontmatter
+(the README skill table is hand-maintained and drifts — do not use it as the source).
+
+## Step 1 — Resolve the team repo
+
+Resolve `TEAM_REPO` exactly as `kickoff` does: the `team-repo-path` Claude memory first,
+else `$CLAUDE_TEAM_REPO`, else probe (`~/toga-tech`, …) for a dir containing
+`knowledge/registry.json`. Persist a `team-repo-path` memory if you had to discover it.
+
+Optionally `git -C "<TEAM_REPO>" pull --rebase --autostash origin _main` first so the list
+reflects skills teammates just pushed. Skip the pull silently if it is not a clone or
+network is unavailable.
+
+## Step 2 — List skills with install status
+
+```bash
+node "<TEAM_REPO>/knowledge.js" skills --installed="<project-root>/.claude/skills"
+```
+
+`<project-root>` is the current working directory's project root (the dir containing
+`.claude`). This prints a table `STATUS  SKILL  DESCRIPTION` where STATUS is one of:
+
+- **installed** — present in this project's `.claude/skills/`; ready to use now.
+- **available** — in the team repo but not installed here → run `/sync-team-skills`.
+- **local-only** — installed locally but absent from the team repo (a personal/unpushed
+  skill, e.g. `worker2-action`). Flag it so the developer can decide whether to contribute it.
+
+## Step 3 — Present and advise
+
+Render the table grouped by status (installed first, then available, then local-only). Then:
+
+- If any row is **available**, tell the developer: "Run `/sync-team-skills` to install these."
+- If any row is **local-only**, note it: "`<skill>` exists only on this machine — if it's
+  useful to the team, add it to `<TEAM_REPO>/skills/` and push."
+- Keep descriptions to one line each; the full skill prose lives in its `SKILL.md`.
+
+## Notes
+
+- This is read-only discovery. It never installs or modifies skills — that's
+  `/sync-team-skills`'s job.
+- The canonical skill source is `<TEAM_REPO>/skills/*/SKILL.md` (what `sync-skills.js`
+  copies from), not the repo's `.claude/skills/` (an untracked local install).