@theronap/agnoclast-mcp 0.9.96

package/skills/log/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: cortex-log
+description: Close out a work session into Agnoclast — summarize what happened, confirm it reached the org, and surface anything teammates should know. Run at or near the end of any working session.
+---
+
+> **Agnoclast-managed skill.** This file is installed and kept up to date by Agnoclast. Local edits are
+> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
+
+## Model: session-primary, daily-derived
+
+The **session is the primary atomic unit** — one session = one durable Agnoclast record (via
+`log_session`, keyed by `sessionId`), which is also the per-record privacy unit (`set_record_privacy`
+is per record). Any "what happened today / this week" view is a **derived rollup** over those session
+records, never a separately-authored primary. This mirrors records(atomic) → digests(derived); the
+personal `/log` skill follows the same shape against the local brain.
+
+## When to use
+
+At the end of a Claude Code session, or after finishing a meaningful phase of work. Agnoclast keeps a
+background auto-capture as a fallback, but this skill is the *authoritative* close-out: it composes a
+clean, structured summary and persists THAT as the session's durable record (superseding the
+auto-capture's raw-transcript re-derivation).
+
+## Inputs
+
+No arguments. Read the conversation context.
+
+## Steps
+
+1. **Summarize the session** — what was worked on, what was decided, what changed. Be concrete: name
+   the projects, files, and people involved.
+2. **Surface org-relevant signal** — blockers, decisions, handoffs, and anyone you coordinated with.
+   These are the things a teammate or manager would want to know without reading the whole transcript.
+3. **Persist it as the durable record** — call the `log_session` MCP tool with your curated `summary`
+   (plus `project`, and the Claude Code `sessionId` if you know it). This writes YOUR summary as the
+   session's authoritative Agnoclast record (`capture_source='skill'`). The background auto-capture is a
+   fallback and will not overwrite it; passing the same `sessionId` the auto-capture uses dedupes them
+   onto one record. This — not the raw-transcript re-derivation — is the canonical record going forward.
+
+   ⚠ **If you belong to more than one brain, pass `brain`.** ADR-0022 deleted the write pointer, so a
+   session-class source routes only by an explicit brain or a sole membership — omit it and the log is
+   **STAGED, not recorded**, and staged session logs are not drainable by `/api/staged/promote`. Pick the
+   brain the work was actually in (`my_brains` shows what each holds). This silently swallowed 86 close-outs
+   before it was caught on 2026-08-09.
+4. **Confirm + flag privacy** — **read the result text, do not assume it succeeded.** `log_session` now
+   answers `NOT LOGGED — STAGED…` or `NOT LOGGED — the server skipped…` when no record was written; only a
+   message carrying a record id means it landed. (It previously printed "Logged … updated existing" for a
+   staged write, because `inserted` is merely falsy when nothing is recorded — an agent reported a session
+   as saved when it was not.) If it errors, tell the user to run `npx -y @theronap/cortex-mcp doctor`.
+
+   If any record from this session should be confidential, prefer passing `privacy: "confidential"` on the
+   `log_session` call itself so it is tiered **at write time** rather than landing org-visible and being
+   corrected after. Otherwise note it so the user can mark it (`set_record_privacy`). Default is org-visible
+   under access rules.
+5. **Sweep the wiki (author what you now understand)** — the HARD backstop for live authoring
+   ([[cortex-wiki-authoring-spec]] D2). For each node whose understanding meaningfully advanced this
+   session (the project(s) worked on, people you coordinated with, and yourself when your own focus
+   shifted): call `authoring_context` for its kind, then `author` to write the page from your compiled
+   understanding — what it IS, where it stands, dated decisions, open threads, key people — with inline
+   `[[links]]` to other nodes (canonical names from the namespace; red-links for wanted-but-absent
+   nodes). This is a synthesis, not a transcript dump. Skip nodes you didn't actually advance. If you
+   already authored a node mid-session and nothing changed since, `author` will report "no change" —
+   that's fine.
+6. **Sweep pending documentation** — run `npx -y @theronap/cortex-mcp docs-scan --json`; if any
+   docs are pending, follow the `cortex-author-docs` skill (author each into its page, then
+   `docs-scan --mark`). Specs/plans written to disk this session must not die on disk — a spec IS
+   a page. If no roots are registered or nothing is pending, skip silently.
+7. **Reconcile the sweep (don't trust it).** Step 5 relies on your in-the-moment judgment of "what
+   advanced"; this step closes the loop so nothing is silently missed. Before printing the Output:
+   a. **Enumerate what you touched** — from the transcript, list the concrete entities this session
+      advanced: the project(s), notable files/artifacts, and the people you coordinated with. Derive
+      this checklist from what actually *happened*, not from what you remember authoring — the whole
+      point is to catch the node you forgot.
+   b. **Assert one outcome per entity** — every item gets exactly `authored [[Page]]` **or**
+      `skipped — <reason>` (e.g. "no material change", "not a node", "already current"). Nothing may be
+      left unaccounted for. If an entity that genuinely advanced has neither, `author` it now (Step 5).
+   Carry the tally into the Output.
+
+   > **A read-back verification sub-step lived here and was REMOVED 2026-07-31. Do not re-add it
+   > without new evidence.** It asked you to `read_page` every page you had just authored, to confirm
+   > the write landed. Measured over 397 local transcripts — 18 sessions that wrote a page,
+   > 2026-07-29→31 — **18 `author` calls were rejected and all 18 were retried to success: zero
+   > silently lost.** An end-of-session pass would have caught nothing, because the rejection reason
+   > arrives *in the tool result at the moment of the call*. Session end is the weakest place to
+   > verify a write; the result you already have in hand is the strongest.
+   >
+   > **What replaces it — at the moment of each write, not at the end:** a rejected `author` comes back
+   > as an ORDINARY tool result with **no error flag** — `Could not author "<page>": Agnoclast API 409:
+   > <reason>` — and `No change to "<page>"` is a **200 OK that wrote nothing**. Neither is an error at
+   > the protocol level, so nothing will interrupt you. **Read the result text of every write; never
+   > skim it.** That inline read is where this step's value actually was.
+
+## Output
+
+After calling `log_session`, show a short structured summary:
+
+```markdown
+## Session summary
+
+**Worked on:** brief description
+**Decisions:** decision 1; decision 2
+**Open / blocked:** anything unresolved or waiting on someone
+**Coordinated with:** people involved
+**Logged:** ✅ persisted as the session's record (authoritative)  (or ⚠ log_session errored — run doctor)
+**Wiki authored:** [[Node A]], [[Node B]] — pages updated (or "— nothing advanced this session")
+**Reconciled:** N touched → M authored, K skipped (reason each)
+```
+
+## Safety rules
+
+- This skill summarizes and persists the session's record (via `log_session`). It never sends external
+  messages, never deletes anything, and never changes access on a record without the user explicitly asking.
+- Raw session text stays on this machine — only the curated summary-grade record reaches the org, scoped
+  by access rules.

package/skills/walkthrough/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: cortex-walkthrough
+description: Run the guided Agnoclast walkthrough for someone new. Use when the person asks for the walkthrough, a tutorial, or getting started — "give me the walkthrough", "walk me through this", "how do I use this", "show me around", "what can this do", "remind me how this works" — or when a brand-new user needs orienting for the first time.
+---
+
+> **Agnoclast-managed skill.** This file is installed and kept up to date by Agnoclast. Local edits are
+> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
+
+# The Agnoclast walkthrough
+
+You are orienting someone who is probably **not technical** and did not ask for a lecture. Treat
+this file as a script to perform, not a document to display.
+
+## The rules, in priority order
+
+1. **Never paste this file at them.** Say the first idea in your own words, ask one question, wait.
+   A wall of text is a failed walkthrough even if every word is correct.
+2. **No jargon. None.** Do not say *node, page, tier, MCP, grep, authoring, graph, retrieval,
+   scoped, red-link, records, timeline*. Say "I wrote that down", not "I authored a node". This is
+   not a style preference — it is the measured failure mode of this product. A new user was given
+   identifier-dense terminology and had to stop and ask what the assistant was talking about.
+   *Brain* is the one term you may introduce, and only in walkthrough 3.
+3. **Use their real life immediately.** Never demo with a made-up example. Ask what is actually on
+   their plate and build the walkthrough out of their answer. Someone who ends this holding a list
+   of their own real things is converted; someone who watched a demo is not.
+4. **Do it, don't describe it.** When they mention something, write it down for real, then show them
+   it came back. The first run must end with something true stored and retrieved — not with them
+   understanding an architecture.
+5. **One step at a time, and check in.** After each step: *"want to keep going, or is that enough for
+   now?"* Stopping early is a success. Say so.
+6. **When they ramble, that is the product working.** Do not redirect them to be more concise.
+   Extract from the mess yourself. Their willingness to talk sloppily is the behaviour you want.
+7. **Never make them feel behind.** No streaks, no "you haven't used this in a while", no half-done
+   setup checklists. If they return after three weeks, pick up like nothing happened.
+8. **If they ask what it costs or how it works underneath, answer plainly and briefly, then get back
+   to their stuff.** Do not pitch.
+
+**You are done when** they have said something real, you stored it, and they saw it come back. Ten
+minutes, one loop closed. Everything else is optional.
+
+## Opening
+
+Say roughly this, in your own words:
+
+> Agnoclast is a memory you and I share. Anything you tell me — a decision, something you need to do,
+> how something works, what someone said — gets written down in one place I read before I answer you.
+> So you stop re-explaining your own life every time you open a chat. It remembers; you don't have to.
+> It's Jarvis, minus the flying suit.
+
+Then offer the menu below and let them pick. If they don't care, start with walkthrough 1.
+
+---
+
+## Walkthrough 1 — keeping track of your life
+
+*The one most people should do first. About ten minutes.*
+
+**The problem it solves:** the cost of holding a hundred small things in your head isn't the
+forgetting, it's the background hum of trying not to forget, running all day underneath everything
+else. This puts that down. Unlike every to-do app they have quit, they never maintain it — they
+mention things in passing and later ask what they were supposed to follow up on.
+
+**Step 1 — empty their head.** Ask ONE question and then stop talking: *"What's actually on your
+plate this week?"* Let them talk. Do not interrupt to confirm items or number things back at them
+mid-flow. Interrupting the dump is the most common way to break this.
+
+They will undersell it — most people give three things and stop. Follow up **once**, gently, with a
+specific probe: *"anything you're overdue getting back to?"* That usually yields another five. Once.
+Twice is an interrogation.
+
+**Step 2 — store it for real while they are still talking**, not in a tidy summary at the end. Then
+play it back grouped plainly: what needs doing, what they're waiting on someone else for, what's
+just worth remembering. Do not invent priorities, due dates or categories they didn't give you —
+inventing structure is how this starts feeling like an app they have to maintain.
+
+Invite correction explicitly: *"Tell me what I got wrong."* Then actually change it. The first
+correction is the moment it becomes theirs.
+
+**Step 3 — close the loop, for real.** Start a fresh conversation (or at minimum ask the retrieval
+question and answer it purely from what's stored, saying plainly that a brand-new conversation would
+have seen the same): **"What was I supposed to follow up on?"**
+
+That is the whole point and it must actually happen. They saved no file, named no document, picked
+no folder. They talked, and it came back.
+
+**Step 4 — hand them the one habit that matters**, then stop: *"From now on, whenever something
+lands on you, just say 'don't let me forget X'. That's the whole thing."*
+
+**Never** propose a tagging scheme, folder structure, priority system, daily review ritual or naming
+convention. Every one of those is why they quit the last four apps. If they *ask* for structure,
+give the least you can get away with.
+
+---
+
+## Walkthrough 2 — just tell it what's going wrong
+
+*The one people are most surprised by, and the highest-converting. Also the easiest to run badly.*
+
+**Open by inviting the complaint directly:** *"What's the most annoying thing on your plate right
+now? Don't organise it — just tell me what's going wrong."* Explicit permission to be messy is the
+entire opening move. Do not ask them to "describe a challenge".
+
+**Why it works, if they ask:** a frustrated ramble is a *better* input than a careful question. It's
+loaded with who's involved, what's blocked, what has a deadline and what they're worried about — and
+it took nine seconds. A polished prompt would contain less.
+
+**Then do all three steps in one turn:**
+
+1. **Untangle it.** Give the mess back as its actual separate parts. Most of the relief is here — a
+   mess is heavy mostly because it's undifferentiated.
+2. **Name the load-bearing piece.** Usually one thing blocks everything else, and usually it isn't
+   the part they're angriest about.
+3. **Produce the artifact.** Draft the email. Write the message. Give them the actual words. **Never
+   end on "would you like me to draft that?"** — draft it; they can tell you it's wrong. Stopping at
+   analysis is the single most common way to blow this walkthrough, because step 2 feels complete.
+
+**Then make the persistence visible, once:** *"I've kept the background on this — next time you can
+just say 'the Henderson thing' and I'll know."* One sentence about the benefit. Do not explain how
+storage works.
+
+**Do not clean up their language back at them.** If they were sarcastic or profane, engage with the
+substance in your normal register. Sanitising their framing into corporate-speak reads as
+disapproval and they will start self-editing, which destroys the exact input quality this unlocks.
+
+**Do not moralise about venting.** No "sounds like you're under a lot of stress", no wellness pivot,
+no suggesting a break. They came for leverage, not to be handled. Treat the complaint as information
+and move. Match their energy — if they're being funny about how bad it is, be a little funny back.
+
+**If they push back on the draft, take it and revise immediately without defending it.**
+
+---
+
+## Walkthrough 3 — personal and work, kept separate
+
+*Only run this if they have raised work. Offer once and drop it otherwise — pushing it on someone
+who didn't ask is how onboarding starts feeling like a sales funnel.*
+
+**Lead with the guarantee, not the feature.** Their personal brain is private and unreachable from
+anywhere else. Say that before they ask, because it's the concern they have whether or not they
+voice it.
+
+*Brain* is the one piece of vocabulary you may introduce. Define it once in plain words — "a
+walled-off set of what it knows" — then use it normally. Do not add *tier, scope, org, member,
+permission, isolation* on top.
+
+**The shape:** they have a personal one now. For work they make a second, separate one. Separate
+means separate — the work one cannot reach the personal one, and colleagues invited into the work
+one see only that. The rule that covers ninety percent of cases: *would it be fine if a colleague
+read this?* If they had to think about it, personal.
+
+**Be precise and honest about privacy.** If they ask a pointed question about who can see their data
+— including whether the company operating the product can — answer accurately and without spin. If
+you don't know, say so and offer to find out. A confident wrong answer here is far more damaging
+than an admitted gap.
+
+**Mention employer rules plainly, as useful advice rather than legal throat-clearing:** some
+workplaces and industries have real constraints on putting client or company data into a new system.
+Being the person who checked first is a much better position than the alternative.
+
+**Do not create anything without an explicit yes** — a second brain is a real thing that exists
+afterwards. And if they ask about bringing colleagues in, describe the outcome (shared context, no
+one is the bottleneck, knowledge doesn't leave when someone does), not the mechanics. Walk the
+actual invite only when they say they want to send one.
+
+**Do not coach them on selling it to their boss unless they ask.**
+
+---
+
+## Ten things to try, written the way people actually say them
+
+Offer a few of these when the walkthrough ends, or if someone just wants ideas.
+
+1. *"Here's everything I'm juggling right now"* — then just talk for two minutes.
+2. *"What was I supposed to follow up on?"* — the highest-value question in the product. Monday morning.
+3. *"Remind me what I decided about ___ and why."*
+4. *"I need to write a ___ ."* It already knows the background, so they skip explaining it.
+5. *"What am I forgetting?"*
+6. *"Who was that person who ___ ?"*
+7. *"This is driving me crazy: ___"* — see walkthrough 2.
+8. *"Catch me up on ___ ."* Assembles the story rather than listing.
+9. *"Don't let me forget ___ ."* The one-line capture.
+10. *"What did I do last week?"* Good for status updates, timesheets, and remembering you got things done.
+
+**If they only ever use two, make them #2 and #7.** That is the whole product for most people.
+
+## Closing
+
+Tell them how to come back, once, at the end — and then stop: *"Any time you want this again, just
+say 'give me the walkthrough'."*