mindos

# MindOS Skill

<!-- version: 3.3.1 — CLI-first, MCP optional -->

## CLI commands

Use `mindos file <subcommand>` for all knowledge base operations. Add `--json` for structured output.

| Operation | Command |
|-----------|---------|
| List files | `mindos file list` |
| Read file | `mindos file read <path>` |
| Write/overwrite | `mindos file write <path> --content "..."` |
| Create new file | `mindos file create <path> --content "..."` |
| Append to file | `mindos file append <path> --content "..."` |
| Edit section | `mindos file edit-section <path> -H "## Heading" --content "..."` |
| Insert after heading | `mindos file insert-heading <path> -H "## Heading" --content "..."` |
| Append CSV row | `mindos file append-csv <path> --row "col1,col2,col3"` |
| Delete file | `mindos file delete <path>` |
| Rename/move | `mindos file rename <old> <new>` |
| Search | `mindos search "query"` |
| Backlinks | `mindos file backlinks <path>` |
| Recent files | `mindos file recent --limit 10` |
| Git history | `mindos file history <path>` |
| List spaces | `mindos space list` |
| Create space | `mindos space create "name"` |

> **MCP users:** If you only have MCP tools (`mindos_*`), use them directly — they are self-describing via their schemas. Prefer CLI when available (lower token cost).

### CLI setup

```bash
npm install -g @geminilight/mindos
# Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>
```

---

## Rules

1. **Bootstrap first** — list the KB tree to understand structure before searching or writing.
2. **Default to read-only.** Only write when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
3. **Rule precedence** (highest wins): user's current-turn instruction → `.mindos/user-preferences.md` → nearest directory `INSTRUCTION.md` → root `INSTRUCTION.md` → this SKILL's defaults.
4. **Multi-file edits require a plan first.** Present the full change list; execute only after approval.
5. After create/delete/move/rename → **sync affected READMEs** automatically.
6. **Read before write.** Always read a file before overwriting it. Never write based on assumptions.
7. **Close the turn cleanly.** Match the requested action and stop there; do not add a needless follow-up question after a complete lookup or write.
8. **Respect the source-code boundary.** This skill is for the MindOS KB. If the user asks to edit app/source code and no source file or code workspace tool is available, ask for the concrete repo/file/code context instead of searching or writing KB notes. For a bare coding request, do not use KB list/search/read tools to hunt for source files.

---

## Answer contract

Use this completion contract before any optional post-task hook:

- **Lookup / summary / quote:** Answer first, cite the stable file path(s), and explicitly avoid writes. If the user named a specific local file path, include that exact path in the final answer. If the user said not to modify or asked for read-only handling, end with a short no-change sentence in the user's language (Chinese: "未做任何修改。"; English: "No changes were made."). Do not end with "want me to save/record/update this?" unless the user asked for a next step or the evidence is incomplete.
- **Write / update / append:** Only after a write tool succeeds, report the exact path and operation in the user's language. English: `Saved to <path>`, `Updated <path>`, `Appended to <path>`. Chinese: `已保存到 <路径>`、`已更新 <路径>`、`已追加到 <路径>`。Add at most one short summary sentence.
- **Uploaded content write:** If the user asks to turn uploaded content into a note and the target type is clear, use the uploaded content directly, do at most one light structure/README check, then write the note. Do not stop after directory listing.
- **Clarification:** Ask one concrete question only when the missing answer would change destination, scope, cost, safety, or reversibility. Offer 2-3 realistic options when helpful.
- **Missing evidence or tool failure:** Say what was not found or what failed, name the attempted source/tool when useful, and give the next concrete recovery step. For missing-evidence lookups, do not offer to save, record, create, or add the missing idea unless the user asked to capture it. Never return an empty answer.
- **Language fidelity:** Preserve the user's language and the source note's key terms. If a note uses a Chinese term, reuse that term; put an English gloss in parentheses only when it helps.
- **Read-only completion:** If the user asked for a summary, meeting context, or next step only, stop after answering. Do not append an unsolicited "want me to save/record/draft/write/supplement/amend/export/run this?" offer. End with a declarative sentence, not a question. When following a SOP or workflow, cite the SOP/workflow path used. If the user asked only for the next step, do not ask whether to execute it.

---

## Retrieval strategy

When retrieving knowledge, use **two paths in parallel**, then filter before deep-reading:

### Path 1: Directory scan (by name/structure)

Browse the KB tree and **look at file names and directory names**. Titles often reveal content without reading. If a user asks about "authentication", and you see `Decisions/auth-jwt-vs-session.md`, that's a strong candidate — read it directly, no search needed.

- After bootstrap, scan the tree for paths whose names relate to the query topic.
- Pay attention to directory semantics: `Decisions/`, `Projects/`, `Workflows/`, `Resources/` etc. each imply what kind of content lives there.
- If the KB is small (<50 files), a quick tree scan may be faster and more reliable than search.

### Path 2: Full-text search (by content)

Use `search` for content that can't be guessed from file names alone.

- Craft queries from the user's actual words. If the user says "那个很慢的接口", search for "慢 接口" or "性能 API".
- One well-targeted search is better than 4 vague ones. Only add a second search if the first returned <