mulmoclaude 0.1.0

package/server/workspace/helps/sandbox.md

@@ -0,0 +1,90 @@
+# Sandbox
+
+MulmoClaude runs the Claude Code agent inside a **Docker sandbox** when Docker is available. This isolates the agent's file-system access and limits what it can do on the host.
+
+## How It Works
+
+- On each agent invocation, the server checks whether Docker is running.
+- If Docker is available (and `DISABLE_SANDBOX` is not set), Claude Code runs inside a disposable container (`mulmoclaude-sandbox`) built from `Dockerfile.sandbox`.
+- If Docker is not available, Claude Code runs directly on the host with the workspace as its working directory.
+
+## What the Container Can Access
+
+| Mount | Container path | Mode |
+|---|---|---|
+| Workspace | `/home/node/mulmoclaude` | read-write |
+| `node_modules/` | `/app/node_modules` | read-only |
+| `server/` | `/app/server` | read-only |
+| `src/` | `/app/src` | read-only |
+| `~/.claude/` | `/home/node/.claude` | read-write |
+| `~/.claude.json` | `/home/node/.claude.json` | read-write |
+
+The container runs with `--cap-drop ALL` and as the host user's UID/GID, so it has no elevated privileges.
+
+## Disabling the Sandbox
+
+Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available.
+
+## Host Credentials (opt-in)
+
+The sandbox is credential-free by default. Two opt-in flags let you expose the minimum needed for `git` / `gh` to authenticate without leaking private keys into the container:
+
+- `SANDBOX_SSH_AGENT_FORWARD=1` — forwards the host's SSH agent socket (private keys stay on the host).
+- `SANDBOX_MOUNT_CONFIGS=gh,gitconfig` — allowlisted read-only config mounts.
+
+Full contract, what's deliberately excluded, and troubleshooting: [`docs/sandbox-credentials.md`](../../docs/sandbox-credentials.md).
+
+## Checking the Current Sandbox State
+
+Two places surface what's actually attached to **your** running container — useful when you've just toggled an opt-in flag and want to confirm it took effect.
+
+### From the UI — lock icon popup
+
+Click the 🔒 icon in the top bar. The popup shows:
+
+- **Sandbox enabled / disabled** — whether Docker was detected and `DISABLE_SANDBOX` is off.
+- **Host credentials attached** (only when the sandbox is on):
+  - **SSH agent**: `forwarded` when `SANDBOX_SSH_AGENT_FORWARD=1` **and** `$SSH_AUTH_SOCK` points at a live socket. If the flag is on but the socket is missing, the popup shows `not forwarded` and the server log carries the reason.
+  - **Mounted configs**: allowlisted names from `SANDBOX_MOUNT_CONFIGS` whose host path exists. Names you typed but whose host path is missing are silently dropped from the UI (they appear in the server log as `config mount skipped`).
+
+The popup also has a **sample query button** that asks Claude to summarise this information in natural language.
+
+### From inside a chat session
+
+Inside the container, you can verify each piece directly:
+
+```bash
+# SSH agent — lists identities the host agent will sign with
+ssh-add -l
+
+# gh config — mounted read-only, so `gh auth status` should succeed
+ls /home/node/.config/gh && gh auth status
+
+# gitconfig — mounted read-only
+cat /home/node/.gitconfig
+```
+
+### From the server log
+
+The popup intentionally exposes **names only**, never host paths or skip reasons. Full debug detail lives in the server log:
+
+- `[sandbox] host credentials attached to container` — one-line summary of what was mounted on agent spawn.
+- `[sandbox] unknown SANDBOX_MOUNT_CONFIGS entries ignored` — typo in the CSV.
+- `[sandbox] config mount skipped (host path missing)` — name is in the allowlist but the host file/dir doesn't exist.
+- `[sandbox] SSH agent forward requested but skipped` — flag on but `$SSH_AUTH_SOCK` unset or non-existent.
+
+If the popup isn't showing what you expect, grep the startup log for `[sandbox]` first.
+
+## First-Time Setup (macOS)
+
+On macOS, the Docker container uses a separate credential store from the host. Before using the sandbox for the first time (and whenever the credential expires), run:
+
+```
+yarn sandbox:login
+```
+
+This opens an interactive `claude login` session inside the container so that the sandbox has valid credentials.
+
+## Building the Image
+
+The sandbox image is built automatically on first use. If `Dockerfile.sandbox` changes, the image is rebuilt on the next agent invocation. No manual build step is needed.

package/server/workspace/helps/spreadsheet.md

@@ -0,0 +1,43 @@
+# Spreadsheet Authoring Guide
+
+Reference for the `presentSpreadsheet` plugin. Read this before building a spreadsheet.
+
+## Cell Format
+
+Every cell is an object `{"v": value, "f": format}`.
+
+- `v` — value: text, number, date string, or formula (string starting with `=`)
+- `f` — optional format code for display
+
+## Formulas
+
+Set `v` to a string starting with `=`. Use Excel-style A1 cell references.
+
+```json
+{"v": "=B2*1.05", "f": "$#,##0.00"}
+{"v": "=SUM(A1:A10)", "f": "#,##0"}
+```
+
+Never pre-calculate — let the spreadsheet compute using cell refs, functions, and arithmetic.
+
+## Available Functions
+
+SUM, AVERAGE, COUNT, MIN, MAX, IF, AND, OR, NOT, ROUND, ABS, TODAY, DATE, DATEDIF, YEAR, MONTH, DAY, CONCATENATE, LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER, VLOOKUP, INDEX, MATCH, PMT, FV, PV, NPV, IRR.
+
+## Dates
+
+Use date strings like `01/15/2025` or date formulas like `=TODAY()` or `=DATE(2025,1,15)`. The spreadsheet auto-parses common formats (MM/DD/YYYY, YYYY-MM-DD, DD-MMM-YYYY) into date serial numbers. Date arithmetic works: `=B2-TODAY()` calculates days between dates.
+
+## Format Codes
+
+| Code | Use |
+|---|---|
+| `$#,##0.00` | Currency |
+| `#,##0` | Integer with commas |
+| `0.00%` | Percent |
+| `0.00` | Decimal |
+| `MM/DD/YYYY` | Date |
+| `DD-MMM-YYYY` | Date |
+| `YYYY-MM-DD` | ISO date |
+
+Format is optional for plain text/numbers.

package/server/workspace/helps/telegram.md

@@ -0,0 +1,135 @@
+# Telegram Bridge
+
+The Telegram bridge lets you talk to your MulmoClaude from the Telegram app on your phone or desktop. Your own custom Telegram bot forwards messages to the MulmoClaude server running on your computer, and replies come back through the same bot.
+
+This is useful when you want to reach your MulmoClaude away from your computer — on a walk, from a phone, or from a friend's device — without exposing the server to the public internet.
+
+## How It Works
+
+- You create a **bot** with Telegram's BotFather; it gives you a token.
+- You run a **bridge process** (`yarn telegram`) on the same machine as the MulmoClaude server. The bridge uses your bot token to receive messages from Telegram, forwards them to MulmoClaude over `localhost:3001`, and sends the replies back to the Telegram user.
+- A short **allowlist** of Telegram chat IDs controls who can talk to the bot. Everyone else gets `"Access denied"`.
+
+Your computer has to be on and connected to the internet for the bot to respond. Close the laptop → the bot goes silent.
+
+## Prerequisites
+
+- MulmoClaude checked out and runnable (`yarn dev` works).
+- A Telegram account.
+- Two terminals free: one for `yarn dev`, one for `yarn telegram`.
+
+## Step 1 — Create the Bot with BotFather
+
+1. In Telegram, search for `@BotFather` (the official account has a blue check) and start a chat.
+2. Send `/newbot`.
+3. Answer the two prompts:
+   - **Display name** — what appears in the chat header. Anything, e.g. `"Alice's MulmoClaude"`.
+   - **Username** — must end in `bot` and be unique on Telegram, e.g. `alice_mulmoclaude_bot`.
+4. BotFather replies with a **token** like `1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw`. This token is the bot's password — anyone who has it can impersonate the bot. Keep it secret.
+
+Optional polish (can be done anytime later via BotFather):
+
+- `/setdescription` — text shown when users open the chat for the first time.
+- `/setuserpic` — the bot's avatar.
+- `/setprivacy` → `Disable` — lets the bot see all messages in group chats (by default it only sees messages starting with `/`).
+
+## Step 2 — Start MulmoClaude and the Bridge
+
+In terminal A, start MulmoClaude:
+
+```bash
+yarn dev
+```
+
+Wait until you see `[server] listening port=3001`.
+
+In terminal B, start the bridge. Leave the allowlist **empty on purpose** for the first run — you will need to discover your own chat ID before you can add it.
+
+```bash
+export TELEGRAM_BOT_TOKEN='1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw'
+export TELEGRAM_ALLOWED_CHAT_IDS=''
+yarn telegram
+```
+
+Expected output:
+
+```
+MulmoClaude Telegram bridge
+Allowlist: (empty — all chats will be denied)
+Connected (<socket id>).
+```
+
+## Step 3 — Find Your Chat ID and Allowlist It
+
+1. In Telegram, open your new bot (search the username you picked) and send it any message — `hi` works.
+2. In terminal B, you will see a log line like:
+   ```
+   [telegram] denied chat=987654321 user=@alice — not on allowlist
+   ```
+   That number (`987654321`) is **your Telegram chat ID**.
+3. Stop the bridge (`Ctrl+C`), put your ID in the allowlist, restart:
+
+   ```bash
+   export TELEGRAM_ALLOWED_CHAT_IDS='987654321'
+   yarn telegram
+   ```
+
+4. Send the bot another message. MulmoClaude should now reply.
+
+## Step 4 — Invite a Friend
+
+To let another person use your MulmoClaude:
+
+1. Share the bot's username with them; they search for it on Telegram and send it a message.
+2. Their chat ID appears in terminal B's `denied` log line, just like yours did in Step 3.
+3. Append their ID (comma-separated) and restart the bridge:
+
+   ```bash
+   export TELEGRAM_ALLOWED_CHAT_IDS='987654321,123456789'
+   yarn telegram
+   ```
+
+4. When they message the bot again, it works.
+
+To avoid re-exporting every time, put `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ALLOWED_CHAT_IDS` in a `.env` file at the repo root. The bridge auto-loads `.env` on startup via `dotenv/config`, so the vars take effect just by restarting `yarn telegram` — no shell `export` needed.
+
+```dotenv
+# .env (repo root)
+TELEGRAM_BOT_TOKEN=1234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
+TELEGRAM_ALLOWED_CHAT_IDS=987654321,123456789
+```
+
+## Bot Commands
+
+These are typed directly into the Telegram chat. They mirror the CLI:
+
+- `/help` — show available commands.
+- `/reset` — start a fresh conversation session (drops prior context).
+- `/roles` — list available roles.
+- `/role <id>` — switch to a specific role (e.g. `/role office`).
+- `/status` — show the current session info (session ID, current role).
+
+Any other text is treated as a message to the assistant.
+
+## Troubleshooting
+
+**`Connect error: bearer token rejected`** — MulmoClaude was restarted, so its bearer token changed. Restart `yarn telegram` to pick up the new one. To avoid this, pin `MULMOCLAUDE_AUTH_TOKEN` to the same value on both sides (see `docs/developer.md` §Auth).
+
+**`TELEGRAM_ALLOWED_CHAT_IDS: "foo" is not an integer chat id`** — typo in the allowlist. Chat IDs are plain integers only — no spaces, quotes, or `#` prefix. Negative integers (for group chats) are allowed.
+
+**Friend gets `"Access denied"` after you added their ID** — the allowlist is read once at startup. Restart `yarn telegram` after changing `TELEGRAM_ALLOWED_CHAT_IDS`.
+
+**Messages stop flowing with no error** — check that `yarn dev` is still running. If the MulmoClaude server is down, the bridge stays up but has nothing to forward to. The next inbound message will log `Connect error` or `Disconnected`.
+
+**Bot responds in a group chat you did not expect** — group chat IDs are **negative**. If you want the bot to work in a specific group, add that negative ID. By default BotFather enables "group privacy mode", so the bot only sees messages starting with `/` in groups — toggle it via BotFather's `/setprivacy` if you need full visibility.
+
+## Security Notes
+
+- The bot token is a password. If it leaks, regenerate it via BotFather's `/revoke`.
+- The allowlist is the only thing standing between "my friends" and "every Telegram user on Earth". Keep it current — remove chat IDs when you no longer want that person to have access, and restart the bridge.
+- The bridge logs chat IDs, usernames, and message lengths, but **not** message contents or the bot token. If you need a full audit trail, record it separately.
+- The MulmoClaude bearer token never leaves your machine. The bridge only talks to `localhost:3001`; your friends talk to Telegram's servers, which then talk to your bridge.
+
+## Full Operator Guide
+
+For the complete operator walkthrough (including screenshots-worthy step numbering and a Japanese translation), see `docs/message_apps/telegram/README.md` (English) and `docs/message_apps/telegram/README.ja.md` (Japanese) in the MulmoClaude repository.

package/server/workspace/helps/wiki.md

@@ -0,0 +1,131 @@
+# Wiki
+
+The wiki is a personal knowledge base that Claude builds and maintains as interconnected Markdown files in the workspace. It is available in the **General** role.
+
+The idea originated from [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
+
+## The Core Idea
+
+Most people's experience with LLMs and documents resembles RAG: upload files, retrieve relevant chunks at query time, generate answers. The LLM rediscovers knowledge from scratch on every question — there is no accumulation.
+
+The wiki is different. Instead of retrieving from raw documents at query time, Claude **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of Markdown files. When you add a new source, Claude doesn't just index it. It reads it, extracts key information, and integrates it into the existing wiki: updating entity pages, revising topic summaries, noting contradictions, strengthening synthesis.
+
+**The wiki is a persistent, compounding artifact.** Cross-references are already there. Contradictions are flagged. The synthesis reflects everything you've read. The wiki grows richer with every source and every question.
+
+You never write the wiki yourself — Claude writes and maintains all of it. You curate sources, explore, and ask questions. Claude does the summarizing, cross-referencing, filing, and bookkeeping.
+
+## What You Can Do With It
+
+- **Research**: go deep on a topic over weeks or months — reading papers, articles, reports, building a comprehensive wiki with an evolving thesis.
+- **Reading a book**: file each chapter as you go, building pages for characters, themes, plot threads, and connections.
+- **Personal knowledge**: track goals, health, self-improvement — file journal entries, articles, podcast notes, and build a structured picture over time.
+- **Business**: feed Slack threads, meeting transcripts, project documents into a wiki that stays current because Claude does the maintenance.
+
+## Your Role vs. Claude's Role
+
+**Your job**: curate sources, direct the analysis, ask good questions, think about what it all means.
+
+**Claude's job**: summarizing, cross-referencing, filing, updating pages, maintaining consistency, bookkeeping — everything that makes humans abandon wikis because the maintenance burden grows too fast.
+
+## Three Operations
+
+### Ingest
+
+Drop a source (article, URL, text) and ask Claude to process it.
+
+Claude will: read the source, identify key entities and concepts, create or update 5–15 wiki pages, add cross-references, append a log entry, and refresh the index. Show the updated index in the canvas when done.
+
+### Query
+
+Ask any question. Claude searches `data/wiki/index.md` for relevant pages, reads them, and synthesizes a grounded answer with citations. Good answers can be filed back into the wiki as new pages — a comparison you asked for, an analysis, a connection you discovered — so they don't disappear into chat history.
+
+### Lint
+
+Ask Claude to health-check the wiki. It scans for contradictions, stale claims, orphan pages, missing cross-references, and concepts that deserve their own page, then fixes issues automatically.
+
+## Folder Layout
+
+```
+data/wiki/
+  index.md          ← catalog of all pages (title, one-line summary, last updated)
+  log.md            ← append-only chronological activity log
+  summary.md        ← compact key-topics list (loaded into every session as ambient context)
+  SCHEMA.md         ← conventions for page format, index updates, and log entries
+  pages/
+    <topic>.md      ← one page per entity, concept, or theme
+  sources/
+    <slug>.md       ← raw ingested sources (immutable after ingest)
+```
+
+## Page Format
+
+Each page is a plain Markdown file with YAML frontmatter:
+
+```markdown
+---
+title: Transformer Architecture
+created: 2026-04-05
+updated: 2026-04-05
+tags: [machine-learning, architecture, attention]
+---
+
+# Transformer Architecture
+
+Brief summary paragraph...
+
+## Key Concepts
+
+...
+
+## Related Pages
+
+- [[Attention Mechanism]]
+- [[BERT]]
+- [[GPT]]
+```
+
+Cross-references use `[[Page Name]]` wiki-link syntax. Slugs are lowercase, hyphen-separated (e.g. `transformer-architecture.md`).
+
+## `index.md` Format
+
+`data/wiki/index.md` is the catalog — one bullet per page using standard markdown link syntax with the slug embedded in the href. This format works both in-app (the canvas parses it) and in any plain markdown viewer (GitHub, VS Code preview, etc.).
+
+```markdown
+# Wiki Index
+
+## ページ一覧
+
+- [Transformer Architecture](pages/transformer-architecture.md) — machine-learning, architecture, attention (2026-04-05)
+- [さくらインターネット](pages/sakura-internet.md) — クラウド, 日本企業, データセンター (2026-04-06)
+- [ECharts DataZoom](pages/echarts-datazoom.md) — ECharts, データ可視化 (2026-04-13)
+
+## タグ一覧
+
+- **AI**: [Transformer Architecture](pages/transformer-architecture.md), [さくらインターネット](pages/sakura-internet.md)
+- **日本企業**: [さくらインターネット](pages/sakura-internet.md)
+```
+
+Key rules:
+
+- Always write bullet items as `[Title](pages/<slug>.md) — description (YYYY-MM-DD)` — **no** `[[slug]]` wiki-link form, and **no** markdown tables. The canvas parser extracts the slug from the href so non-ASCII titles (日本語, etc.) keep a navigable slug.
+- Slugs are lowercase ASCII, hyphen-separated. They match the page filename one-to-one (`pages/sakura-internet.md` → slug `sakura-internet`).
+- Group by category if useful, then include a "タグ一覧" / "Tags" section with the same `[Title](pages/<slug>.md)` link form so every mention is clickable.
+- Keep the index in sync with `pages/` — when you add a page, add a row; when you rename a file, update every link that points at it.
+
+## Canvas Tool
+
+Use the `manageWiki` tool to display wiki content in the canvas:
+
+- `action: "index"` — show the page catalog
+- `action: "page"` — show a single page (provide `pageName`)
+- `action: "log"` — show the activity log
+- `action: "lint_report"` — run a health check
+
+## Relationship to `memory.md`
+
+|        | `memory.md`                              | `data/wiki/`                                |
+| ------ | ---------------------------------------- | ------------------------------------------- |
+| Scope  | Brief distilled facts, always in context | Deep structured knowledge, loaded on demand |
+| Growth | Intentionally small                      | Grows unboundedly                           |
+
+Over time, Claude can distill key insights from the wiki back into `memory.md` as compact ambient context for all roles.