taskswipe-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # taskswipe-mcp
 
-Your TASK//SWIPE day, from inside Claude Code, Claude Desktop, Codex or Cursor.
+Your TASKKA day, from inside Claude Code, Claude Desktop, Codex or Cursor.
 
 ```
 you: add "call the bank" and "book the dentist" to today
@@ -25,17 +25,40 @@ row-level security still applies and no service key exists anywhere.
 the server reading credentials from your own machine rather than sending a
 token over the wire.
 
-## Setup
+## One-time VPS setup (Hermes / OpenClaw)
 
-You need your TASK//SWIPE login token — that's it. The production Supabase URL
-and anon key are baked in as defaults (they're public — they ship in the web
-app's JS bundle); self-hosters can override them with `TASKSWIPE_SUPABASE_URL`
-and `TASKSWIPE_SUPABASE_ANON_KEY`.
+Run one command in an interactive SSH session as the same Linux user that runs
+the agent:
 
-> **Not on npm yet.** Until `taskswipe-mcp` is published, every client below
-> runs it from this repo by path:
-> `node ~/Developer/swipe-todo-react/mcp/src/index.js`
-> Once it's published, replace that with `npx -y taskswipe-mcp` everywhere.
+```bash
+npx -y taskswipe-mcp@latest setup hermes
+```
+
+or:
+
+```bash
+npx -y taskswipe-mcp@latest setup openclaw
+```
+
+The installer asks for the TASKKA email and password. Password input is hidden;
+the password is used once to mint a separate session for that VPS and is never
+written to disk. The renewable session is saved at
+`~/.taskswipe-mcp-session.json` with mode `0600`, then the installer registers
+the stdio MCP, installs the TASKKA skill and runs the agent's connection check.
+No tunnel, public port, YAML/JSON edit or hourly token copy is involved.
+
+This is safer than copying the browser refresh token: the browser and VPS have
+independent sessions and can rotate their credentials without racing each other.
+
+## Manual setup and other clients
+
+The production Supabase URL and anon key are baked in as defaults (they're
+public — they ship in the web app's JS bundle); self-hosters can override them
+with `TASKSWIPE_SUPABASE_URL` and `TASKSWIPE_SUPABASE_ANON_KEY`.
+
+> **Published:** https://www.npmjs.com/package/taskswipe-mcp — so anywhere the
+> examples below run it by path, `npx -y taskswipe-mcp` works instead and needs
+> nothing checked out.
 
 **Claude Code**
 
@@ -74,6 +97,46 @@ TASKSWIPE_ACCESS_TOKEN = "eyJ..."
 (`codex mcp list` to confirm it registered; note the section is
 `mcp_servers`, snake_case, not `mcpServers`.)
 
+**Hermes Agent** (Nous) — prefer the one-command setup above. Its resulting
+credential-free entry is equivalent to:
+
+```yaml
+mcp_servers:
+  taskka:
+    command: "npx"
+    args: ["-y", "taskswipe-mcp"]
+```
+
+```bash
+hermes skills install https://taskka.app/.well-known/skills/taskka/SKILL.md
+```
+
+The server reads the renewable VPS session from the owner-only session file.
+
+**OpenClaw** — prefer the one-command setup above. Its resulting entry is:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "taskka": {
+        "command": "npx",
+        "args": ["-y", "taskswipe-mcp@latest"]
+      }
+    }
+  }
+}
+```
+
+```bash
+openclaw skills install https://taskka.app/.well-known/skills/taskka/SKILL.md
+openclaw mcp doctor taskka --probe
+```
+
+Hosted HTTP (`https://taskka.app/mcp` + `Authorization: Bearer <access>`) works
+for a Control-UI one-shot. Access tokens die in about an hour — always-on
+Hermes/OpenClaw gateways should use the one-time stdio bootstrap above.
+
 **Claude Desktop / Cursor** — these do use the JSON shape
 (`claude_desktop_config.json` / `.cursor/mcp.json`):
 
@@ -95,7 +158,7 @@ TASKSWIPE_ACCESS_TOKEN = "eyJ..."
 
 ### Getting an access token
 
-Sign in to TASK//SWIPE in a browser, open the console, and run:
+Sign in to TASKKA in a browser, open the console, and run:
 
 ```js
 JSON.parse(Object.entries(localStorage).find(([k]) => k.includes('auth-token'))[1]).access_token
@@ -103,9 +166,9 @@ JSON.parse(Object.entries(localStorage).find(([k]) => k.includes('auth-token'))[
 
 It expires on its own, which is the point — a leaked token stops working.
 
-### Making it permanent
+### Legacy token-seeded sessions
 
-Add `TASKSWIPE_REFRESH_TOKEN` next to it — same console snippet, ending in
+For older configs, add `TASKSWIPE_REFRESH_TOKEN` next to it — same console snippet, ending in
 `.refresh_token` instead of `.access_token`. With the pair in place the server
 renews itself and keeps the CURRENT session in `~/.taskswipe-mcp-session.json`
 (owner-only file). That file matters: Supabase rotates refresh tokens on every
@@ -113,9 +176,10 @@ use and treats reuse of an old one as theft, so the config values are only the
 seed — after first run the file is the live credential. Signing out of that
 session (or deleting the file AND pasting a fresh pair) is the reset path.
 
-### Password fallback
+### Stored-password fallback (not recommended)
 
-`TASKSWIPE_EMAIL` + `TASKSWIPE_PASSWORD` also work, and the server prefers a
+`TASKSWIPE_EMAIL` + `TASKSWIPE_PASSWORD` also work, but this is not what the
+one-time installer does. The server prefers a
 token whenever both are present. Understand the trade before using it: MCP
 config files sit unencrypted in your home directory, are frequently committed
 by accident, and are read by every tool on the machine. A password there is a
@@ -129,9 +193,7 @@ The repo root carries `.codex-plugin/plugin.json` + `.mcp.json`, which makes
 the whole repo an installable Codex plugin. The path to being listed
 (as of 2026-08):
 
-1. **Publish `taskswipe-mcp` to npm** — the plugin manifest runs
-   `npx -y taskswipe-mcp`, which is dead until the package exists.
-   `cd mcp && npm publish --access public` under an npm account.
+1. ~~Publish to npm~~ — **done**. The one-time VPS installer ships in `taskswipe-mcp@0.2.0`.
 2. **Interim listing** — submit the GitHub repo URL to the community registry
    at codex-marketplace.com (automated review of the manifest).
 3. **Official directory** — OpenAI's self-serve publishing is "coming soon";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "taskswipe-mcp",
-  "version": "0.1.0",
-  "description": "Read and write your TASK//SWIPE day from Claude Code, Claude Desktop, Codex or Cursor.",
+  "version": "0.2.0",
+  "description": "Read and write your TASKKA day from Hermes, OpenClaw, Claude Code, Codex or Cursor.",
   "type": "module",
   "bin": {
     "taskswipe-mcp": "src/index.js"

package/src/brief.js

@@ -0,0 +1,310 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// THE BRIEF — the whole system, in about a page.
+//
+// THE PROBLEM. An agent connecting to TASKKA could reach six tools covering
+// three of twenty-five tabs, and had no way to find out what the other
+// twenty-two even were. Answering "how am I doing?" meant guessing which tools
+// existed, calling several, and stitching. Answering anything about food, lifts,
+// money, habits, goals or study was impossible — not because the data was
+// private but because nothing described it.
+//
+// The lazy fix is get_state. That hands over a few hundred KB of arrays so the
+// model can count them itself: slow, expensive, and mostly a waste, because
+// ninety-nine percent of that blob is history nobody asked about.
+//
+// ── WHAT THIS DOES INSTEAD ──────────────────────────────────────────────────
+//
+// SUMMARISE, NEVER SERIALISE. No array goes out whole. Everything is a count,
+// a headline, or the two or three items that actually need a decision. The
+// brief is bounded — roughly the same size for someone on day 900 as on day 3 —
+// because size here should track how much is GOING ON, not how much has ever
+// happened.
+//
+// SIGNALS, NOT DATA. "3 habits missed 4 days" is the sentence an agent can act
+// on. The habits array is a puzzle it has to solve first, badly, every time.
+//
+// SAY WHAT EXISTS. `areas` lists every part of the app with a one-line state,
+// including the empty ones — an agent cannot ask about a tab it has no idea is
+// there, and "nothing logged" is a useful answer to "what should I do next?".
+//
+// LAYERED. The brief is the map. `detail(area)` is the drill-down, and the
+// existing tools do the writing. One cheap call to orient, one targeted call
+// for depth — instead of six calls and a guess.
+//
+// Pure and state-in/JSON-out on purpose, so it can be tested without a network.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const arr = (v) => (Array.isArray(v) ? v : [])
+const num = (v) => (Number.isFinite(+v) ? +v : 0)
+
+const dayStr = (d = new Date()) =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+
+const daysAgo = (n, from = new Date()) => {
+  const d = new Date(from)
+  d.setDate(d.getDate() - n)
+  return dayStr(d)
+}
+
+const lastN = (n, from = new Date()) => Array.from({ length: n }, (_, i) => daysAgo(i, from))
+
+/** A completion is 'YYYY-MM-DD' or {date, kind}; a MISSED day is not a doing. */
+const stackDoneDays = (s) => new Set(arr(s?.completions)
+  .filter(c => (typeof c === 'string' ? true : c?.kind !== 'missed'))
+  .map(c => (typeof c === 'string' ? c : c?.date))
+  .filter(Boolean))
+
+const habitDoneDays = (h) => new Set(arr(h?.completions).map(c => (typeof c === 'string' ? c : c?.date)).filter(Boolean))
+
+/** How many of the last `win` days had a tick — the honest read of a streak. */
+const hitRate = (days, win, from) => lastN(win, from).reduce((n, d) => n + (days.has(d) ? 1 : 0), 0)
+
+const partOfDay = (h) => (h < 5 ? 'night' : h < 12 ? 'morning' : h < 17 ? 'afternoon' : h < 22 ? 'evening' : 'night')
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildBrief(state = {}, now = new Date()) {
+  const today = dayStr(now)
+  const S = state || {}
+
+  // ── TODAY ─────────────────────────────────────────────────────────────────
+  const tasks = arr(S.todayTasks)
+  const open = tasks.filter(t => !t.done)
+  const done = tasks.filter(t => t.done)
+  const timed = open.filter(t => t.at).sort((a, b) => String(a.at).localeCompare(String(b.at)))
+  const hhmm = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`
+
+  // ── ATTENTION: the things a person would want raised ──────────────────────
+  // Ordered by severity so an agent can take the top one and be right most of
+  // the time. This is the part worth reading if it reads nothing else.
+  const attention = []
+
+  const overdue = timed.filter(t => String(t.at) < hhmm)
+  if (overdue.length) {
+    attention.push({ area: 'today', severity: 3,
+      what: `${overdue.length} scheduled ${overdue.length === 1 ? 'task is' : 'tasks are'} past their time`,
+      items: overdue.slice(0, 3).map(t => `${t.at} ${t.text}`) })
+  }
+
+  const missed = arr(S.missedTasks)
+  if (missed.length >= 3) {
+    attention.push({ area: 'today', severity: 1,
+      what: `${missed.length} tasks aged out unfinished and are sitting in DROPPED` })
+  }
+
+  // Habits are the app's committed tier: quiet ones are the real signal.
+  const quietHabits = arr(S.habits)
+    .map(h => ({ name: h.name || h.title, hits: hitRate(habitDoneDays(h), 7, now) }))
+    .filter(h => h.hits === 0)
+  if (quietHabits.length) {
+    attention.push({ area: 'habits', severity: 2,
+      what: `${quietHabits.length} habit${quietHabits.length === 1 ? '' : 's'} untouched for a week`,
+      items: quietHabits.slice(0, 4).map(h => h.name) })
+  }
+
+  const decay = S.decayState || {}
+  if (num(decay.quietStreak) >= 2) {
+    attention.push({ area: 'squares', severity: 2,
+      what: `${decay.quietStreak} quiet days in a row — squares are decaying` })
+  }
+
+  if (!S.coreTask && open.length > 3) {
+    attention.push({ area: 'today', severity: 1,
+      what: `${open.length} things open and nothing named as the one that matters` })
+  }
+
+  attention.sort((a, b) => b.severity - a.severity)
+
+  // ── AREAS: one line each, including the empty ones ────────────────────────
+  const foodToday = arr(S.foodLog?.[today])
+  const kcal = Math.round(foodToday.reduce((n, e) =>
+    n + (num(e.per100?.kcal) * num(e.grams)) / 100, 0))
+  const health = S.healthDaily?.[today] || {}
+
+  const stacks = arr(S.stacks).map(s => ({
+    name: s.name,
+    hits: hitRate(stackDoneDays(s), Math.round((num(s.graduationTarget) || 14) * 1.5), now),
+    target: num(s.graduationTarget) || 14,
+  }))
+  const readyStacks = stacks.filter(s => s.hits >= s.target)
+
+  const goalFrames = S.goals && typeof S.goals === 'object' ? Object.values(S.goals).flat() : []
+  const building = goalFrames.find(g => g?.id === S.activeGoalId)
+
+  const maps = arr(S.studyMaps)
+  const learningTopics = maps.flatMap(m => arr(m.nodes).filter(n => n.status === 'learning')
+    .map(n => `${m.title}: ${n.title}`))
+
+  const areas = {
+    today: `${open.length} open, ${done.length} done${S.coreTask ? `, core: ${S.coreTask.task || S.coreTask}` : ''}`,
+    backlog: `${arr(S.backlogTasks).length} parked`,
+    deck: `${arr(S.deck).length} cards waiting to be swiped`,
+    recurring: `${arr(S.recurringTasks).length} rules`,
+    missions: `${arr(S.missions).filter(m => !m.done).length} open`,
+    goals: goalFrames.length
+      ? `${goalFrames.length} goals${building ? `, building: ${building.text}` : ', none on the crane'}`
+      : 'none set',
+    habits: arr(S.habits).length
+      ? `${arr(S.habits).length} habits, ${arr(S.habits).filter(h => habitDoneDays(h).has(today)).length} ticked today`
+      : 'none',
+    stacks: stacks.length
+      ? `${stacks.length} building${readyStacks.length ? `, ${readyStacks.length} ready to graduate` : ''}`
+      : 'none',
+    food: foodToday.length
+      ? `${kcal} kcal logged today, ${arr(S.pantry).length} foods on the shelf`
+      : `nothing logged today, ${arr(S.pantry).length} foods on the shelf`,
+    lift: `${arr(S.liftSessions).length} sessions logged`,
+    walk: health.steps ? `${health.steps} steps today` : 'no step data today',
+    money: arr(S.moneyTx).length ? `${arr(S.moneyTx).length} transactions` : 'nothing tracked',
+    mind: S.moods?.[today]?.length
+      ? `${S.moods[today].length} check-ins today`
+      : 'no check-in today',
+    day_score: S.dayScores?.[today] ? `${S.dayScores[today].score}/10 posted` : 'not posted',
+    study: maps.length
+      ? `${maps.length} maps, ${learningTopics.length} topics in progress`
+      : 'none',
+    reader: `${arr(S.books).length} books`,
+    parley: `${arr(S.parleyDeck).length} cards`,
+    squares: `${num(S.totalSquares)} total${num(decay.quietStreak) ? `, ${decay.quietStreak} quiet days` : ''}`,
+  }
+
+  return {
+    now: { date: today, time: hhmm, part_of_day: partOfDay(now.getHours()) },
+
+    // The one sentence an agent should lead with. Everything below is evidence.
+    headline: attention[0]?.what
+      || (open.length ? `${open.length} open today, nothing overdue` : 'nothing open today'),
+
+    today: {
+      core_task: S.coreTask?.task || S.coreTask || null,
+      open: open.length,
+      done: done.length,
+      // Only the ones with a time — an untimed list of forty is not a schedule.
+      next: timed.filter(t => String(t.at) >= hhmm).slice(0, 3).map(t => `${t.at} ${t.text}`),
+      overdue: overdue.slice(0, 5).map(t => `${t.at} ${t.text}`),
+      open_titles: open.slice(0, 12).map(t => t.text),
+    },
+
+    attention: attention.slice(0, 6),
+    areas,
+
+    // Where to look next, so an agent does not have to guess which tools exist.
+    drill: {
+      more_on_an_area: "detail(area) — any key from `areas`",
+      today_in_full: 'today()',
+      find_anything: 'search(query)',
+      write: 'add_tasks, complete_task, capture, set_core_task',
+    },
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DETAIL — one area, still summarised.
+//
+// The point of splitting this out is that an agent pays for depth only where it
+// asked for it. Each branch returns the shape someone would actually reason
+// with, not the rows.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildDetail(state = {}, area = '', now = new Date()) {
+  const S = state || {}
+  const today = dayStr(now)
+  const key = String(area || '').toLowerCase().trim()
+
+  switch (key) {
+    case 'today': {
+      const tasks = arr(S.todayTasks)
+      return {
+        open: tasks.filter(t => !t.done).map(t => ({
+          text: t.text, at: t.at || null, category: t.category || null,
+          why: t.why || null, timer: t.timer || null, sticky: !!t.sticky,
+        })),
+        done: tasks.filter(t => t.done).map(t => t.text),
+        dropped: arr(S.missedTasks).slice(0, 20).map(t => t.text),
+      }
+    }
+    case 'habits':
+      return arr(S.habits).map(h => {
+        const days = habitDoneDays(h)
+        return { name: h.name || h.title, today: days.has(today), last_7: hitRate(days, 7, now), lifetime: days.size }
+      })
+    case 'stacks':
+      return arr(S.stacks).map(s => {
+        const days = stackDoneDays(s)
+        const target = num(s.graduationTarget) || 14
+        const window = Math.round(target * 1.5)
+        return {
+          name: s.name, cue: s.anchor || null, minimum: s.minimum || null,
+          hits: hitRate(days, window, now), target, window,
+          ready: hitRate(days, window, now) >= target,
+          today: days.has(today),
+        }
+      })
+    case 'goals': {
+      const frames = S.goals && typeof S.goals === 'object' ? S.goals : {}
+      return Object.entries(frames).flatMap(([frame, list]) => arr(list).map(g => ({
+        frame, text: g.text, bricks: `${num(g.earnedBricks)}/${num(g.targetBricks) || 20}`,
+        building: g.id === S.activeGoalId,
+        steps: arr(g.steps).length ? arr(g.steps).map(st => `${st.stage}: ${st.text}`) : null,
+      })))
+    }
+    case 'food': {
+      const day = arr(S.foodLog?.[today])
+      const tot = day.reduce((a, e) => {
+        const f = num(e.grams) / 100
+        return {
+          kcal: a.kcal + num(e.per100?.kcal) * f,
+          protein: a.protein + num(e.per100?.protein) * f,
+          carbs: a.carbs + num(e.per100?.carbs) * f,
+          fat: a.fat + num(e.per100?.fat) * f,
+        }
+      }, { kcal: 0, protein: 0, carbs: 0, fat: 0 })
+      return {
+        today: day.map(e => `${e.meal}: ${e.name} ${e.grams}${e.unit || 'g'}`),
+        totals: Object.fromEntries(Object.entries(tot).map(([k, v]) => [k, Math.round(v)])),
+        targets: S.foodTargets || null,
+        pantry_size: arr(S.pantry).length,
+        saved_meals: arr(S.meals).map(m => m.name),
+      }
+    }
+    case 'study':
+      return arr(S.studyMaps).map(m => ({
+        map: m.title, aim: m.blurb || null,
+        topics: arr(m.nodes).map(n => ({
+          title: n.title, status: n.status,
+          // The tutor's note is the memory of this topic — the single most
+          // useful thing an agent can read about someone's learning.
+          next: (n.note || '').split(/^##\s+Next\s*$/mi)[1]?.split('\n').map(l => l.trim()).find(Boolean) || null,
+        })),
+      }))
+    case 'lift':
+      return {
+        sessions: arr(S.liftSessions).slice(-8).map(s => ({
+          date: s.date, name: s.name || null,
+          exercises: arr(s.exercises).map(e => e.name).slice(0, 12),
+        })),
+        routines: arr(S.liftRoutines).map(r => r.name),
+      }
+    case 'mind': {
+      // The day note is composed of tagged segments; an agent wants the prose.
+      const segs = arr(S.moodDayJournals?.[today])
+      return {
+        today: arr(S.moods?.[today]).map(m => m.mood || m.key),
+        day_score: S.dayScores?.[today] || null,
+        note: segs.map(x => x.text).filter(Boolean).join(' ').slice(0, 800) || null,
+      }
+    }
+    case 'squares':
+      return {
+        total: num(S.totalSquares),
+        decay: S.decayState || null,
+        recent_losses: arr(S.decayLog).slice(-5),
+      }
+    case 'backlog':
+      return arr(S.backlogTasks).slice(0, 40).map(t => ({ text: t.text, horizon: t.horizon || null }))
+    case 'missions':
+      return arr(S.missions).map(m => ({ title: m.title, done: !!m.done, tasks: arr(m.taskIds).length }))
+    default:
+      return { error: `unknown area "${area}"`, known: Object.keys(buildBrief(S, now).areas) }
+  }
+}

package/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // ─────────────────────────────────────────────────────────────────────────────
-// TASK//SWIPE MCP SERVER — stdio transport.
+// TASKKA MCP SERVER — stdio transport.
 //
 // Transport is deliberately the only thing in this file. Tools live in
 // tools.js and know nothing about MCP; state access lives in store.js and
@@ -23,39 +23,53 @@ import { TOOLS, byName } from './tools.js'
 
 const log = (...a) => process.stderr.write(a.join(' ') + '\n')
 
-const server = new Server(
-  { name: 'taskswipe', version: '0.1.0' },
-  { capabilities: { tools: {} } },
-)
+async function startServer() {
+  const server = new Server(
+    { name: 'taskswipe', version: '0.2.0' },
+    { capabilities: { tools: {} } },
+  )
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: TOOLS.map(t => ({
-    name: t.name,
-    title: t.title,
-    description: t.description,
-    inputSchema: t.inputSchema,
-  })),
-}))
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map(t => ({
+      name: t.name,
+      title: t.title,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    })),
+  }))
 
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-  const tool = byName[req.params.name]
-  if (!tool) {
-    return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }] }
-  }
-  try {
-    const result = await tool.run(req.params.arguments || {})
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
-  } catch (e) {
-    // Returned as a tool error rather than thrown: the model can read it and
-    // tell the user what to fix, instead of the client showing "server error".
-    log(`[taskswipe] ${tool.name} failed:`, e?.message || e)
-    return {
-      isError: true,
-      content: [{ type: 'text', text: `TASK//SWIPE: ${e?.message || 'unknown error'}` }],
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = byName[req.params.name]
+    if (!tool) {
+      return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }] }
     }
-  }
-})
+    try {
+      const result = await tool.run(req.params.arguments || {})
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+    } catch (e) {
+      // Returned as a tool error rather than thrown: the model can read it and
+      // tell the user what to fix, instead of the client showing "server error".
+      log(`[taskswipe] ${tool.name} failed:`, e?.message || e)
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `TASKKA: ${e?.message || 'unknown error'}` }],
+      }
+    }
+  })
 
-const transport = new StdioServerTransport()
-await server.connect(transport)
-log('[taskswipe] MCP server ready on stdio —', TOOLS.length, 'tools')
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  log('[taskswipe] MCP server ready on stdio —', TOOLS.length, 'tools')
+}
+
+try {
+  if (process.argv[2] === 'setup') {
+    const { runSetup } = await import('./setup.js')
+    await runSetup(process.argv.slice(3))
+  } else {
+    await startServer()
+  }
+} catch (error) {
+  log(`TASKKA setup failed: ${error?.message || error}`)
+  process.exitCode = 1
+}

package/src/setup.js

@@ -0,0 +1,175 @@
+// One-time, interactive bootstrap for an always-on TASKKA agent.
+//
+// The account password is read from the terminal with echo disabled, used once
+// to mint a dedicated Supabase session, and never written to disk. The agent
+// then runs taskswipe-mcp without credentials in its config: the renewable
+// session lives in ~/.taskswipe-mcp-session.json with owner-only permissions.
+
+import { spawnSync } from 'node:child_process'
+import process from 'node:process'
+import { persistSession, SESSION_FILE, supa } from './store.js'
+
+const SKILL_URL = 'https://taskka.app/.well-known/skills/taskka/SKILL.md'
+const PACKAGE = 'taskswipe-mcp@latest'
+
+export function parseSetupArgs(argv = []) {
+  const target = String(argv[0] || '').toLowerCase()
+  let email = ''
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === '--email') email = String(argv[++i] || '').trim()
+    else if (String(argv[i]).startsWith('--email=')) email = String(argv[i]).slice(8).trim()
+    else throw new Error(`Unknown setup option: ${argv[i]}`)
+  }
+  if (!['hermes', 'openclaw'].includes(target)) {
+    throw new Error('Usage: taskswipe-mcp setup <hermes|openclaw> [--email you@example.com]')
+  }
+  return { target, email }
+}
+
+export function setupPlan(target) {
+  if (target === 'hermes') {
+    return [
+      {
+        label: 'Registering TASKKA with Hermes',
+        command: 'hermes',
+        args: ['mcp', 'add', 'taskka', '--command', 'npx', '--args', '-y', PACKAGE],
+      },
+      {
+        label: 'Installing the TASKKA skill',
+        command: 'hermes',
+        args: ['skills', 'install', SKILL_URL],
+        optional: true,
+      },
+      {
+        label: 'Testing the MCP connection',
+        command: 'hermes',
+        args: ['mcp', 'test', 'taskka'],
+      },
+    ]
+  }
+  if (target === 'openclaw') {
+    return [
+      {
+        label: 'Registering TASKKA with OpenClaw',
+        command: 'openclaw',
+        args: ['mcp', 'add', 'taskka', '--command', 'npx', '--arg', '-y', '--arg', PACKAGE],
+      },
+      {
+        label: 'Installing the TASKKA skill',
+        command: 'openclaw',
+        args: ['skills', 'install', SKILL_URL],
+        optional: true,
+      },
+      {
+        label: 'Testing the MCP connection',
+        command: 'openclaw',
+        args: ['mcp', 'doctor', 'taskka', '--probe'],
+      },
+    ]
+  }
+  throw new Error(`Unsupported setup target: ${target}`)
+}
+
+function readVisible(question) {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(question)
+    let value = ''
+    const onData = chunk => {
+      const text = chunk.toString('utf8')
+      const end = text.indexOf('\n')
+      if (end !== -1) {
+        cleanup()
+        resolve((value + text.slice(0, end)).replace(/\r$/, '').trim())
+      } else value += text
+    }
+    const onError = error => { cleanup(); reject(error) }
+    const cleanup = () => {
+      process.stdin.off('data', onData)
+      process.stdin.off('error', onError)
+      process.stdin.pause()
+    }
+    process.stdin.on('data', onData)
+    process.stdin.on('error', onError)
+    process.stdin.resume()
+  })
+}
+
+function readSecret(question) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+    throw new Error('Password entry needs an interactive terminal. Re-run this command directly over SSH.')
+  }
+  return new Promise((resolve, reject) => {
+    const value = []
+    process.stdout.write(question)
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+
+    const finish = (error) => {
+      process.stdin.off('data', onData)
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+      process.stdout.write('\n')
+      if (error) reject(error)
+      else resolve(Buffer.from(value).toString('utf8'))
+    }
+    const onData = chunk => {
+      for (const byte of chunk) {
+        if (byte === 3) return finish(new Error('Setup cancelled.'))
+        if (byte === 13 || byte === 10) return finish()
+        if (byte === 8 || byte === 127) {
+          if (value.length) {
+            value.pop()
+            process.stdout.write('\b \b')
+          }
+        } else if (byte >= 32) {
+          value.push(byte)
+          process.stdout.write('•')
+        }
+      }
+    }
+    process.stdin.on('data', onData)
+  })
+}
+
+function runStep(step) {
+  process.stdout.write(`\n${step.label}…\n`)
+  const result = spawnSync(step.command, step.args, { stdio: 'inherit' })
+  if (result.error?.code === 'ENOENT') {
+    throw new Error(`${step.command} is not installed or is not on PATH.`)
+  }
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    if (step.optional) {
+      process.stderr.write(`TASKKA session is connected, but this optional step did not finish.\n`)
+      return
+    }
+    throw new Error(`${step.label} failed (exit ${result.status ?? 'unknown'}).`)
+  }
+}
+
+export async function runSetup(argv = process.argv.slice(3)) {
+  const { target, email: suppliedEmail } = parseSetupArgs(argv)
+  if (!process.stdin.isTTY) {
+    throw new Error('One-time setup needs an interactive terminal. Run it directly in your VPS SSH session.')
+  }
+
+  process.stdout.write('\nTASKKA · ONE-TIME VPS SETUP\n')
+  process.stdout.write('Your password is used once to create this agent session. It is never saved.\n\n')
+  const email = suppliedEmail || await readVisible('TASKKA email: ')
+  if (!email || !email.includes('@')) throw new Error('Enter a valid TASKKA email address.')
+  let password = await readSecret('TASKKA password: ')
+  if (!password) throw new Error('Password cannot be blank.')
+
+  const { data, error } = await supa().auth.signInWithPassword({ email, password })
+  password = ''
+  if (error || !data?.session || !data?.user) {
+    throw new Error(`TASKKA sign-in failed: ${error?.message || 'no session returned'}`)
+  }
+  persistSession(data.session)
+  process.stdout.write(`Signed in as ${data.user.email || email}. Renewable session saved to ${SESSION_FILE}\n`)
+
+  for (const step of setupPlan(target)) runStep(step)
+
+  process.stdout.write(`\n✓ TASKKA is paired with ${target === 'hermes' ? 'Hermes' : 'OpenClaw'}.\n`)
+  process.stdout.write('You can leave it alone now; the MCP session renews itself.\n')
+}

package/src/store.js

@@ -1,7 +1,7 @@
 // ─────────────────────────────────────────────────────────────────────────────
 // STATE ACCESS — read/modify/write the one JSONB blob, safely.
 //
-// TASK//SWIPE keeps everything in a single `user_states.state` row, upserted
+// TASKKA keeps everything in a single `user_states.state` row, upserted
 // whole. With one writer that is fine. MCP adds a SECOND writer, and a plain
 // upsert means last-write-wins — the web app saves, we save a moment later
 // from a stale read, and everything it just did is silently gone.
@@ -80,7 +80,7 @@ export function supa() {
 // So the pasted-into-config token pair is only ever the SEED: after the first
 // refresh, the current pair lives in this file and the env values are stale by
 // design. Delete the file to start over from the env seed.
-const SESSION_FILE = path.join(os.homedir(), '.taskswipe-mcp-session.json')
+export const SESSION_FILE = path.join(os.homedir(), '.taskswipe-mcp-session.json')
 
 function loadSavedSession() {
   try {
@@ -89,17 +89,25 @@ function loadSavedSession() {
   } catch { return null }
 }
 
+export function persistSession(session) {
+  fs.writeFileSync(
+    SESSION_FILE,
+    JSON.stringify({
+      access_token: session.access_token,
+      refresh_token: session.refresh_token,
+      expires_at: session.expires_at || null,
+    }),
+    { mode: 0o600 },
+  )
+  // writeFile's mode only applies when a file is first created. Correct an
+  // older or manually-created file too, so the credential is always private.
+  fs.chmodSync(SESSION_FILE, 0o600)
+  return SESSION_FILE
+}
+
 function saveSession(session) {
   try {
-    fs.writeFileSync(
-      SESSION_FILE,
-      JSON.stringify({
-        access_token: session.access_token,
-        refresh_token: session.refresh_token,
-        expires_at: session.expires_at || null,
-      }),
-      { mode: 0o600 },   // it's a credential — owner-only, like an SSH key
-    )
+    persistSession(session)
   } catch (e) {
     console.error('[taskswipe] could not persist session:', e?.message)
   }

package/src/tools.js

@@ -14,6 +14,7 @@
 // ─────────────────────────────────────────────────────────────────────────────
 
 import { readState, mutate } from './store.js'
+import { buildBrief, buildDetail } from './brief.js'
 
 const MAX_ADD = 10
 const uid = () => Math.random().toString(36).slice(2, 11)
@@ -23,6 +24,27 @@ const today = () => {
 }
 
 const arr = (v) => (Array.isArray(v) ? v : [])
+const num = (v) => (Number.isFinite(+v) ? +v : 0)
+
+// Mirrors GOAL_FRAMES and creditGoal in src/lib/goals.js. Duplicated rather
+// than imported because this package ships standalone to npm and cannot reach
+// into the app's src/. If the goal model changes there, change it here too.
+const GOAL_FRAMES = ['3month', '6month', 'yearly', '3year', '7year']
+function creditGoal(goals = {}, { goalId, goalFrame, squares }) {
+  if (!goalId || !squares) return goals || {}
+  const frames = goalFrame && GOAL_FRAMES.includes(goalFrame) ? [goalFrame] : GOAL_FRAMES
+  const next = { ...(goals || {}) }
+  for (const frame of frames) {
+    const list = arr(next[frame])
+    const idx = list.findIndex(g => g.id === goalId)
+    if (idx < 0) continue
+    next[frame] = list.map((g, i) => (i === idx
+      ? { ...g, earnedBricks: Math.max(0, num(g.earnedBricks) + squares) }
+      : g))
+    return next
+  }
+  return goals || {}
+}
 
 /** Match a task the way a person refers to it: by substring, not by id. */
 function findTask(list, ref) {
@@ -43,11 +65,53 @@ function findTask(list, ref) {
 }
 
 export const TOOLS = [
+  // FIRST CALL, ALWAYS. Six tools covering three of twenty-five tabs left an
+  // agent guessing what existed and stitching several reads into a picture. One
+  // bounded call now describes the whole system — see brief.js for why it
+  // summarises rather than serialising.
+  {
+    name: 'brief',
+    title: 'The whole picture, briefly',
+    description:
+      'START HERE for anything about how the user is doing, what they should do '
+      + 'next, or what is going on in any part of their life. Returns a compact '
+      + 'snapshot of the ENTIRE app — today, what needs attention ranked by '
+      + 'severity, and a one-line state for every area (habits, stacks, goals, '
+      + 'food, lift, walk, mind, study, squares and the rest). About a kilobyte '
+      + 'whether they joined yesterday or two years ago. Follow with detail() '
+      + 'for depth on one area.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    async run() {
+      const { state } = await readState()
+      return buildBrief(state)
+    },
+  },
+
+  {
+    name: 'detail',
+    title: 'One area, in depth',
+    description:
+      'Depth on ONE area named by brief(). Pass any key from the brief\'s '
+      + '`areas` — today, habits, stacks, goals, food, lift, mind, study, '
+      + 'squares, backlog, missions. Still summarised: you get what someone '
+      + 'would reason with, not the raw rows.',
+    inputSchema: {
+      type: 'object',
+      properties: { area: { type: 'string', description: 'e.g. "habits", "food", "study"' } },
+      required: ['area'],
+      additionalProperties: false,
+    },
+    async run({ area }) {
+      const { state } = await readState()
+      return buildDetail(state, area)
+    },
+  },
+
   {
     name: 'today',
     title: "Today's plan",
     description:
-      "What TASK//SWIPE has for today: open and completed tasks, the core task, "
+      "What TASKKA has for today: open and completed tasks, the core task, "
       + "the day score if posted, and today's timed blocks. Call this before "
       + "answering anything about what the user is doing today.",
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
@@ -130,10 +194,19 @@ export const TOOLS = [
       + 'a few words is enough, no id needed. Returns the exact task matched.',
     inputSchema: {
       type: 'object',
-      properties: { task: { type: 'string', minLength: 1, description: 'Any part of the task text.' } },
+      properties: {
+        task: { type: 'string', minLength: 1, description: 'Any part of the task text.' },
+        squares: {
+          type: 'integer', minimum: 0, maximum: 48,
+          description:
+            'How many squares the task was worth. Omit unless the user says — '
+            + 'a recurring rule with a preset worth supplies its own, and '
+            + 'anything else is worth 0 until the user values it in the app.',
+        },
+      },
       required: ['task'], additionalProperties: false,
     },
-    async run({ task }) {
+    async run({ task, squares }) {
       let result = null
       await mutate(state => {
         const list = arr(state.todayTasks)
@@ -141,10 +214,52 @@ export const TOOLS = [
         if (!hit) { result = { ok: false, reason: 'no_match' }; return null }
         if (hit.ambiguous) { result = { ok: false, reason: 'ambiguous', candidates: hit.ambiguous }; return null }
         if (hit.done) { result = { ok: true, already: true, task: hit.text }; return null }
-        result = { ok: true, task: hit.text }
+
+        // Mirrors the COMPLETE_TASK reducer in src/store.jsx. Ticking a task is
+        // not just a flag: it earns squares, writes a history entry, feeds the
+        // level counter, and credits any linked stack or goal. Setting `done`
+        // alone — which is all this did — silently dropped every one of those,
+        // so a recurring task configured as worth 8 earned nothing when ticked
+        // from here. Keep the two in step.
+        //
+        // Coerce like the reducer does: one non-finite value would make
+        // totalSquares NaN, and NaN survives every later addition, quietly
+        // destroying the currency for good.
+        const asked = squares !== undefined ? squares : hit.presetSquares
+        const earned = Number.isFinite(+asked) ? Math.max(0, +asked) : 0
+
+        const newToday = list.map(t => (t.id === hit.id
+          ? {
+              ...t, done: true, completedAt: Date.now(),
+              // Settling the parent settles its steps, as the app does.
+              ...(t.subtasks ? { subtasks: t.subtasks.map(sub => ({ ...sub, done: true })) } : {}),
+            }
+          : t))
+
+        const entry = {
+          ...hit, done: true, squares: earned,
+          stackId: hit.stackId, notes: '', at: Date.now(), source: 'mcp',
+        }
+        if (!entry.goalId) { delete entry.goalId; delete entry.goalFrame }
+
+        const newTotal = num(state.totalSquares) + earned
+        const leveledUp = earned > 0
+          && Math.floor(num(state.totalSquares) / 48) !== Math.floor(newTotal / 48)
+
+        const newStacks = hit.stackId
+          ? arr(state.stacks).map(st => (st.id === hit.stackId
+              ? { ...st, completions: [...arr(st.completions), { date: today(), task: hit.text }] }
+              : st))
+          : state.stacks
+
+        result = { ok: true, task: hit.text, squares: earned, total: newTotal, leveledUp }
         return {
           ...state,
-          todayTasks: list.map(t => (t.id === hit.id ? { ...t, done: true, completedAt: Date.now() } : t)),
+          todayTasks: newToday,
+          achievedTasks: [entry, ...arr(state.achievedTasks)],
+          totalSquares: newTotal,
+          stacks: newStacks,
+          goals: earned > 0 ? creditGoal(state.goals, { goalId: entry.goalId, goalFrame: entry.goalFrame, squares: earned }) : state.goals,
         }
       })
       if (!result?.ok && result?.reason === 'no_match') {
@@ -153,7 +268,15 @@ export const TOOLS = [
       if (result?.reason === 'ambiguous') {
         return { ok: false, message: `That matches several: ${result.candidates.join(', ')}. Be more specific.` }
       }
-      return { ok: true, message: result.already ? `"${result.task}" was already done.` : `Ticked off "${result.task}".` }
+      if (result.already) return { ok: true, message: `"${result.task}" was already done.` }
+      const earned = result.squares
+        ? ` +${result.squares} square${result.squares === 1 ? '' : 's'} (${result.total} total)`
+        : ''
+      return {
+        ok: true,
+        message: `Ticked off "${result.task}"${earned}.`
+          + (result.leveledUp ? ' That completed a brick — level up.' : ''),
+      }
     },
   },