@mmmbuto/nexuscrew 0.9.12 → 0.9.13

package/skills/cellforge/assets/internal-prompt.template.md

@@ -0,0 +1,62 @@
+# Internal prompt — starting template
+
+This is the short text the cell receives at boot. Keep it a **pointer**, not a
+manual: it is capped at 8 KB, and anything duplicated from the canonical
+documents will disagree with them within a week.
+
+Replace every `{{PLACEHOLDER}}`. Delete the sections that do not apply — an
+unedited template produces cells that all describe themselves identically, which
+defeats the point of giving them separate identities.
+
+**Never put a credential, token or key in here.** Depending on the engine, this
+text becomes a command-line argument, and command lines are readable by other
+processes belonging to the same user. Refer to the mechanism that holds a
+secret; never to its value.
+
+---
+
+```
+You are the {{CELL_ID}} cell.
+
+PURPOSE. {{One sentence a stranger could act on. Not a department name —
+what this cell produces and for whom.}}
+
+YOU OWN. {{The directories, repositories or document areas this cell is
+responsible for.}}
+
+NOT YOURS. {{What belongs to other cells. Say who owns it, so a request that
+lands here can be redirected instead of refused.}}
+
+FIRST, EVERY SESSION.
+1. Read your canonical prompt and your checkpoint: {{PATH_TO_CANONICAL_DOCS}}
+2. Load your memory: state namespace {{STATE_NAMESPACE}}, journal
+   {{JOURNAL_NAMESPACE}}.
+3. If the checkpoint is open, resume from the recorded point before starting
+   anything else. If it is closed, do not invent work.
+4. Write the checkpoint at start, at every milestone, at every handoff, and
+   when you stop — even if the answer is "nothing changed".
+
+NEVER WITHOUT ASKING. {{The irreversible things in this domain: publishing,
+sending, deleting, deploying, spending. Be specific — a vague limit is one
+that gets rationalised away at 2am.}}
+
+WHEN YOU ARE UNSURE. Say what you did not verify. An honest gap is useful; a
+plausible reconstruction is not, because it cannot be told apart from a fact.
+
+{{OPTIONAL — REVIEW. Who checks this cell's work, and what it may not
+approve on its own.}}
+```
+
+---
+
+## What makes this prompt work, or not
+
+- **The purpose line does most of the work.** If it could describe two different
+  cells, it is too vague, and every session will drift a little differently.
+- **"Not yours" prevents more damage than "yours".** Cells collide over
+  ownership, not over ambition.
+- **The confirmation list is what the user will thank you for.** It is the part
+  that stops a bad afternoon, and it belongs in the prompt rather than in a
+  document the cell might not read.
+- **The last line is not decoration.** A cell that reports what it did not check
+  is one you can trust on what it did.

package/skills/cellforge/references/anatomy.md

@@ -0,0 +1,73 @@
+# Anatomy: the three places a cell lives
+
+A cell is complete when all three exist and agree. Most breakage is one of them
+missing or drifting, and none of the three reports the other two.
+
+```
+1. DEFINITION          the runtime record — engine, cwd, prompt, permissions
+   written through the API, never by editing the file
+
+2. RUNTIME WORKSPACE   ~/NexusFiles/<session>/
+   inbox/  outbox/  + links to the cell's canonical documents
+
+3. CANONICAL DOCUMENTS <docs-repo>/<cells-path>/<CellId>/
+   prompt · checkpoint · history/
+```
+
+## 1. Definition
+
+Covered in `definition.md`. The thing to carry here: it is what makes the cell
+*run*, and it is the only one of the three that has schema validation. The other
+two are conventions — nothing stops you from creating a malformed workspace, so
+the discipline has to come from you.
+
+## 2. Runtime workspace
+
+Lives under the files root, in a directory named after the cell's session. What
+you find inside:
+
+- **`inbox/`** — files delivered to the cell.
+- **`outbox/`** — files the cell offers back to the operator. Created when first
+  needed rather than up front, so its absence on a new cell is normal, not a
+  fault.
+- **links to the canonical documents** — the cell's prompt, its checkpoint and
+  its history are usually **symbolic links** pointing into the documentation
+  repository, not real files.
+
+That last point is the one that causes trouble. When you inspect a cell, resolve
+the links before concluding anything: a checkpoint that looks present may be a
+link to a target that no longer exists, which reads as "the file is there" to
+anything that does not follow it. Equally, a *copy* where a link belongs is
+worse than a missing file — it will be edited, it will diverge from the canonical
+version, and both will look authoritative.
+
+## 3. Canonical documents
+
+The cell's durable identity, versioned in a documentation repository:
+
+- **the internal-facing prompt document** — the long-form version of what the
+  cell is, which the short boot prompt points at;
+- **the checkpoint** — what the cell is doing right now, kept small enough to be
+  read at the start of every session;
+- **`history/`** — previous checkpoints, archived automatically, so the live
+  checkpoint never has to carry the past.
+
+`lifecycle.md` covers who writes these and when.
+
+## Telling a complete cell from a half one
+
+Check in this order — it goes from cheapest to most revealing:
+
+1. **Does the runtime listing show it**, with the engine and model you expect?
+   If the definition is missing, nothing else matters.
+2. **Does the workspace exist**, and do its links resolve to real files? A
+   broken link is the most common silent failure.
+3. **Do the documents exist and describe this cell?** A prompt copied from
+   another cell and never adapted is technically present and practically
+   useless — read it, do not just check that it is there.
+4. **Does the cell have somewhere to write its memory?** See `lifecycle.md`.
+   A cell whose memory namespace was never created will appear to work and will
+   quietly start every session with nothing.
+
+A cell that fails 3 or 4 is the dangerous case: it runs, it answers, and it
+forgets. Nobody notices until someone asks it what it did last week.

package/skills/cellforge/references/audit.md

@@ -0,0 +1,94 @@
+# Auditing a cell
+
+An audit answers one question: **does this cell exist completely, and does it
+match the standard?** Each check below says what to observe, because a check
+whose result you cannot describe in advance is not a check.
+
+Report everything, fix nothing until the user agrees. See the rule at the end —
+it is the one that decides whether audits keep getting run.
+
+## The checks
+
+**1 · The definition loads and is the one you think.**
+Observe the runtime listing, not the definitions file. Expect: the cell present,
+with the engine, model and working directory you expect. A cell absent from the
+listing but present in the file means the document failed validation — the whole
+document, not just that entry.
+
+**2 · The working directory is portable.**
+Expect a relative form alongside the absolute one. Older cells often have only
+the absolute path: not broken, but it will not survive being restored on another
+machine. Offer to normalise.
+
+**3 · The workspace exists and its links resolve.**
+Expect the cell's directory under the files root, and the document links
+resolving to real files. Two failure shapes: a **dangling link** (looks present
+to anything that does not follow it) and a **real file where a link belongs**
+(will be edited, will diverge, and both copies will look authoritative).
+
+**4 · The internal prompt is this cell's.**
+Read it. Expect it to name this cell's purpose and point at its documents.
+A prompt copied from another cell passes every automated check and fails the
+only one that matters. Also confirm it is a *pointer*, not a duplicate of the
+canonical document — duplicates diverge.
+
+**5 · No secrets in the prompt.**
+Expect zero credentials, tokens or keys. This is not stylistic: with flag-style
+delivery the prompt becomes a command-line argument, readable by other processes
+of the same user. Report any find as a live exposure, not a style issue, and
+treat rotation as the user's decision to make with full information.
+
+**6 · The tool grant matches the purpose.**
+Expect either an explicit server list, or a deliberate decision that this cell
+gets everything. An empty list is the widest possible grant, and it is usually
+absence of a decision rather than a decision. Report it as a question, not a
+defect.
+
+**7 · The checkpoint is within limits and correctly shaped.**
+Expect it inside the line and byte limits (`lifecycle.md` gives concrete
+starting numbers), with the sections in the order the install uses — the
+template in `assets/checkpoint.template.md` is the reference shape — and a link
+to the archived history. Over the limit is not a
+style problem: the checkpoint is read at the start of every session.
+
+**8 · The checkpoint's state is honest.**
+Expect `open` to mean someone must resume it, and `closed` to mean verified
+completion. The failure to look for is a checkpoint closed after a crash or a
+restart — those interrupt work, they do not finish it.
+
+**9 · The memory namespace exists and is split.**
+Expect a state namespace and a journal namespace, scoped to this cell. Do not
+check this by looking for a creation step — on many memory servers a namespace
+simply exists once something is written to it. **Check the round trip**: the
+cell writes its state, and reads it back.
+
+Two failures worth naming: memory that never round-trips (the cell starts empty
+every session, which reads as a model problem and can go unnoticed for weeks),
+and **dated keys accumulating in state** (startup gets slower every week, and
+nobody attributes it to this).
+
+**10 · One checkpoint per cell per device.**
+If the identity runs on more than one machine, expect one file per device.
+A shared file means each device overwrites the others silently.
+
+## Prove the audit can fail
+
+Run the checks against a deliberately broken throwaway cell — remove a link,
+close a checkpoint that should be open — and confirm the relevant check goes
+red. A check that has passed on every cell you ever pointed it at may be
+detecting nothing, and you will believe it precisely because it always agrees
+with you.
+
+This costs a few minutes once and is the difference between an audit and a
+ritual.
+
+## Report before you repair
+
+Present findings and proposed fixes, and apply only what the user approves.
+
+The reason is practical, not procedural: an audit that silently changes things
+becomes a thing users are afraid to run. You want them running it often, which
+means it must be safe — and "safe" means it never surprises them.
+
+When you do apply fixes, apply them one at a time and re-run the specific check
+after each. A batch that fails partway leaves nobody sure which half landed.

package/skills/cellforge/references/choosing.md

@@ -0,0 +1,75 @@
+# Choosing an engine, tools and MCP servers for a purpose
+
+This is the step where a cell becomes useful or becomes generic. The goal is a
+recommendation the user can correct, not a questionnaire and not a default.
+
+## Start from the work, not from the roles that already exist
+
+The strong temptation on an install with existing cells is to clone the nearest
+one. Resist it: you inherit its assumptions, its tool grants and its blind
+spots, and the new cell ends up describing itself in someone else's words.
+
+Instead, ask what the work actually looks like, because that maps to engines and
+tools far better than a job title does:
+
+- **Is it mostly reading and drafting, or mostly changing things?** Drafting
+  work wants a capable model and few dangerous tools. Work that edits real
+  systems wants tighter permissions and a reviewer.
+- **Does it need to reach outside** — the web, mail, a calendar, a repository
+  host? Each of those is an MCP server, and each is a grant.
+- **How long is a single task?** Work that runs for hours needs a cell that
+  checkpoints well and can hand off. Work in short bursts does not.
+- **Does the output need to be trusted by someone else?** If yes, plan a second
+  cell to review it. A single cell approving its own work is not a review, and
+  no prompt wording changes that.
+
+## A role the install has never seen
+
+"Marketing", "Support", "Legal ops" — a role with no precedent is the normal
+case, not the exception, and it is where cloning fails hardest.
+
+Work it out from first principles:
+
+1. **What does it produce?** Documents, decisions, messages, code, analysis.
+2. **What does it need to see** to produce that, and what should it never see?
+   This is the MCP list, and phrasing it as "never see" surfaces limits a
+   capability list would miss.
+3. **What is irreversible in its domain?** Sending, publishing, spending,
+   deleting. These become explicit confirmations in the prompt.
+4. **Who checks it?** Either a person, or a second cell, or nobody — and if
+   nobody, say so out loud, because that is a decision.
+
+Then propose engine, model and tools with a sentence of reasoning each, and mark
+what you are unsure about. A recommendation with visible reasoning can be
+corrected; a confident list cannot.
+
+## Scoping MCP servers
+
+A cell with no explicit server list inherits **everything** the client engine
+has. That is the widest grant available, and on most installs it is the default
+simply because nobody set the field.
+
+For a new cell, propose the narrow list: the servers its purpose actually needs.
+The cost is one array, and the benefit is that a drafting cell cannot reach a
+tool that deletes things.
+
+Two cautions:
+
+- **Do not narrow an existing cell without asking.** Something it does today may
+  depend on a server you are about to remove, and the failure will appear later
+  and somewhere else.
+- **Names, not definitions.** The server definitions live in the client
+  configuration and stay there. A per-cell list selects from them; it never
+  redefines them, because two definitions of the same server will drift.
+
+## Permissions and the reviewer
+
+Match the permission posture to what the cell can break, not to how much you
+trust the model. Some engines only accept the standard posture — the API will
+refuse the others, which is a useful signal rather than an obstacle.
+
+When work needs a verdict, the reviewer must be **structurally** independent: a
+different cell, which did not do the work and cannot quietly fix it. A cell that
+implements and then audits its own output will approve it — not from
+dishonesty, but because it is checking against the same understanding that
+produced the work. That is the whole reason the second cell exists.

package/skills/cellforge/references/definition.md

@@ -0,0 +1,107 @@
+# The cell definition
+
+The definition is the runtime record of a cell: what it runs, where, with which
+prompt and permissions. It is stored in the fleet definitions file, but **you
+never edit that file** — you go through the API, which validates the whole
+document and refuses to write a state the file format would happily hold.
+
+## Write path
+
+| operation | endpoint | capability required |
+|---|---|---|
+| create a cell | `POST /define-cell` | `define` |
+| change a cell | `POST /edit-cell` | `edit` |
+| delete a cell | `POST /remove-cell` | `remove` |
+| bulk restore | `POST /restore-cells` | `restore` |
+| create / change / delete an engine | `POST /define-engine`, `/edit-engine`, `/remove-engine` | `define` / `edit` / `remove` |
+
+Two behaviours worth knowing before you are surprised by them:
+
+- **Read-only mode refuses every write with `403`.** If a define or edit comes
+  back refused and the payload looks correct, check whether the fleet provider
+  is read-only before you start rewriting the payload.
+- **Validation is all-or-nothing.** A malformed optional field does not collapse
+  into "absent" — it fails the whole definition. This is deliberate: absent and
+  malformed are opposite outcomes that look alike, and silently treating one as
+  the other is how a cell ends up running with a setting nobody chose.
+
+## Fields
+
+`id` and the tmux session are **immutable after creation** — an edit that
+includes either is refused. Everything else is patchable.
+
+| field | required | shape and limit |
+|---|---|---|
+| `id` | yes | `[A-Za-z0-9._-]`, 1–32 chars. Human-readable identity; the dot is allowed |
+| `cwd` | yes | working directory, ≤4096 chars |
+| `cwdRel` | recommended | the same directory expressed relative to the user's home |
+| `engine` | yes | must reference an existing engine id; a dangling reference fails the definition |
+| `boot` | no | boolean, default false — whether the cell starts with the service |
+| `model` / `models` | no | model selection; validated against the engine's catalogue when the engine is managed |
+| `prompt` | no | the internal prompt, ≤8192 bytes |
+| `permissionPolicies` | no | per-engine permission posture; some engines accept only the standard one |
+| `commands` | no | per-engine command string, shell engines only, ≤4096 chars, no control characters |
+| `panelUrl` | no | HTTP(S) endpoint of an associated panel, ≤512 chars |
+| `mcp` | no | **names only**, up to 64, each matching `[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}` |
+| `label`, `tmuxSession` | varies | display label ≤64 chars; session name ≤64 chars, immutable |
+
+Ceilings on the document as a whole: **32 cells**, **24 engines**. These are not
+close to most installs, but a restore that silently dropped entries would be
+worse than one that fails, so a document over the cap is rejected rather than
+truncated.
+
+## `cwd` and `cwdRel`: portability is a write-time invariant
+
+`cwdRel` is the portable form: the working directory relative to the user's
+home. The distinction matters when a definition moves between machines — an
+absolute path that exists on one install may not exist on another, and the cell
+comes back pointing somewhere wrong or nowhere at all.
+
+Reading tolerates a definition that has only `cwd`, so older entries keep
+loading. **Writing does not**: create and edit resolve the pair together and
+refuse input that is not portable. When you write a definition, always provide
+the relative form — and when you audit an install, expect to find older cells
+that predate it and offer to normalise them.
+
+## `mcp`: the field that grants tools, and why it is probably empty
+
+`mcp` lists **which MCP servers this cell gets, by name**. Only names: the
+server definitions live in exactly one place, the client configuration, and
+duplicating them per cell would create two sources of truth that drift.
+
+Expect to find this field unset on most installs — and understand what that
+means: **a cell with no `mcp` list inherits every server the client engine has.**
+That is convenient and it is also the widest possible grant.
+
+When you create a cell, propose the narrow list that matches its purpose. A
+marketing cell that drafts copy has no business holding a tool that can delete
+files or move money, and the cost of scoping it is one array. Say plainly that
+this is a change from the install's habit, and let the user decide — do not
+narrow an existing cell's tools without asking, because something it does today
+may depend on a server you are about to take away.
+
+## The internal prompt, and the one rule about it
+
+The internal prompt is the text the cell receives at boot. Keep it small — a
+bootstrap that tells the cell who it is and points at its canonical documents,
+not a copy of them. The limit is 8 KB, but the reason to stay far below it is
+that a prompt duplicating the documents will disagree with them within a week.
+
+**How it is delivered depends on the engine**, and this has a security
+consequence:
+
+- **flag delivery** — the prompt is appended to the launch command as an
+  argument. Command lines are visible to other processes of the same user.
+- **typed delivery** — the prompt is sent into the session after it comes up,
+  and re-sent on restart.
+
+So: **never put a credential, token or key in a cell prompt.** Refer to the
+mechanism that holds the secret, never the value. This holds regardless of
+delivery mode — you should not have to know the engine's delivery style to be
+safe, and an engine change must never turn a safe prompt into an exposed one.
+
+The second consequence: **changing the engine can change whether the prompt
+arrives at all.** Verify delivery after any engine change rather than assuming
+the field carried over — the field is still there either way, which is what
+makes this easy to miss. `operations.md` §Verifying that the prompt actually
+arrived has the method for each delivery mode.

package/skills/cellforge/references/lifecycle.md

@@ -0,0 +1,100 @@
+# Lifecycle: prompt, checkpoint, history, memory
+
+Four mechanisms carry a cell across sessions. They are easy to confuse because
+they all "remember things", so start with what each is actually for:
+
+| mechanism | answers | changes |
+|---|---|---|
+| **internal prompt** | who am I, where do I look | rarely — when the purpose changes |
+| **canonical prompt document** | the long-form version of the same | occasionally |
+| **checkpoint** | what am I doing *right now*, and what blocks it | constantly |
+| **memory** | durable facts and a running journal | every session |
+
+## The internal prompt: small on purpose
+
+The boot prompt should establish identity and point at the canonical documents,
+not restate them. Two reasons, and the second is the one people learn the hard
+way:
+
+1. It is capped (8 KB), so a prompt that grows into a manual eventually stops
+   fitting.
+2. **Duplicated instructions diverge.** When the prompt and the document say
+   different things, the cell follows whichever it read last, and no one can
+   tell which that was. One source, one pointer.
+
+## The checkpoint: a resume point, not a diary
+
+The checkpoint answers "if this session ended right now, what would the next one
+need?" That framing decides what belongs in it far better than any rule.
+
+What makes checkpoints work in practice:
+
+- **Hard limits.** A line count and a byte size — as a starting point, **200
+  lines and 24 KB**, with roughly **three days** of operational detail and older
+  work compressed to a summary. They are not bureaucracy: the checkpoint is read
+  at the start of every session, so a bloated one costs context forever.
+  Nothing in the product enforces this. If the install has tooling that
+  validates and archives, use it; if not, the contract still holds and you keep
+  it by hand — which mostly means deleting what is no longer true each time you
+  write.
+- **A fixed section order**, so a reader finds the current task, the evidence,
+  the blockers and the next step in the same place every time.
+- **Automatic archiving.** Replacing the checkpoint should snapshot the previous
+  one into a history tree and leave a link behind. This is what lets the live
+  file stay short without losing anything: the past is one click away, not in
+  your context.
+- **Closed only when verified.** A crash, a reboot, a device change or "I think
+  it worked" do not close a task. Open means someone must resume it.
+
+**Write it even when nothing happened.** A session that starts, finds nothing to
+do and updates the timestamp is doing the right thing: the next session learns
+that the state was checked at a known moment, which is different from not
+knowing.
+
+**One cell writes one checkpoint.** If the same cell identity runs on more than
+one machine, give each device its own checkpoint file — a shared one means each
+device silently overwrites the others, and nobody notices until two sessions
+disagree about reality.
+
+## Memory: state and journal are different mechanisms
+
+Not two files — two behaviours, and using the wrong one is the usual cause of a
+slow, bloated startup.
+
+- **State** — a declarative snapshot of what is true now. Written whole (or
+  patched key by key), read at every startup. It must stay lean, which means
+  **never accumulate dated keys in it**. "What happened on the 14th" is not
+  state; state is "where the work stands".
+- **Journal** — an append-only, bounded event stream. Each entry is stamped and
+  old entries are pruned automatically. Bounded is the contract, not a defect:
+  anything that must survive pruning does not belong here, it belongs in the
+  canonical documents.
+
+Because the journal is bounded and multi-writer safe, it is the right place for
+"what I did this session". Because state is read at every boot, it is the wrong
+place for anything historical.
+
+**Scoping.** Give each cell its own state and journal namespace, tied to a
+per-cell device identity. Reads are typically open across cells — that is what
+lets one cell understand another's situation — while **writes are scoped to the
+owner**. Design for that: a cell should never need to write outside its own
+namespace to do its job, and if it does, the boundary is drawn wrong.
+
+**Getting the namespace to exist** is the memory server's business, not the
+fleet API's, and servers differ: on many, a namespace simply comes into being
+the first time something is written to it, and there is no separate creation
+step to perform. So do not go looking for a command that may not exist — check
+the memory server's own tool surface, and verify the round trip instead: have
+the cell write its state once, then read it back.
+
+Verify it, though. A cell whose memory has nowhere to go does not fail loudly;
+it just starts every session empty, and that reads as a model problem rather
+than a setup problem — which is why it can go unnoticed for weeks.
+
+## Retiring a cell
+
+Removing a cell throws away an identity and orphans its documents. Before doing
+it, confirm with the user and decide explicitly what happens to the canonical
+documents and the memory namespace — usually they should be kept, because they
+are the record of work that actually happened. Stopping a cell is reversible;
+removing its definition and deleting its history is not.