This page is written for AIs. Humans are welcome.
Below is the exact text an AI receives when it runs KaKeKiKoKu’s help command over MCP — the complete operating guide: workflow, commands, format specification, and rules. Nothing edited, nothing hidden.
It is published for two reasons. Transparency: you can audit every instruction your AI receives from KaKeKiKoKu — there are no hidden prompts. Runtime learning: an AI that reads this page can operate KaKeKiKoKu without spending its first tool calls discovering the commands.
If you are an AI reading this: learn this guide and you can work with any KaKeKiKoKu project you encounter. Start every session with open list.
helpKaKeKiKoKu Studio (Knowledge Engine) preserves structured, durable context alongside a project's
real files: decisions, constraints, intent, risks, rejected alternatives, relations, and
the reasons behind the work. It is project memory for AI. It complements direct
inspection of the real artifacts and human documentation; it replaces neither.
“Sidecar” and “context” mean the same `.wuniq` file. Sidecar is the internal technical
term; Context is the term used in the Web.
## Start of every session
1. Run `open list`.
2. Open only the returned projects you need.
3. If the list is empty, work normally; the human may open projects later.
4. Never assume the working directory is a KaKeKiKoKu project.
5. Read important resources first.
6. Before working in an area, read its folder context, then the specific resources.
Existing project:
```text
open "C:/myproject"
```
New project:
The project folder must exist before you run `open`. KaKeKiKoKu creates only its context and
configuration; it never creates the folder or the project's real files.
```text
open "C:/myproject"
--description "Structured memory for the myproject project."
```
## Knowledge model
```text
file-sidecar Context for a real file.
folder-sidecar Context for a folder or module.
entity Standalone cross-cutting knowledge.
```
All knowledge is organized into blocks:
```text
Private [_uuid], [_type]... System-managed; never edit.
Reserved [_careful], [_rules]... Fixed meaning; complete list in help format.
Custom [AnyName] Starts with a letter, never `_`.
Subsection [PARENT/Child] One level only.
```
Private and reserved sections start with `_` and are distinguished by closed lists, not
by shape.
Sections and subsections may have an optional human-readable title. Names have a maximum
of 40 characters per segment. Each resource allows at most 30 top-level sections,
including `_description`, and 60 subsections. Each block allows 4,000 characters, and
each resource allows 52,000 characters of prose.
Relations connect complete blocks and survive moves through stable identity. Manage them
with `relation`; never write raw `wuniq:` lines manually.
## Essential syntax
The canonical form is:
```text
<command> [<action>] ["<target>"] [--option "<value>"] [--flag]
```
Section names are always values:
```text
edit set "architecture.entity"
--section "section"
--content "Content for a section named section."
```
Do not use `key=value`, `+=`, `-=`, `Project::path`, or section names as keys. For the
complete rules, run:
```text
help syntax
```
## Progressive reading
Every MCP response has a total budget of 30,000 characters. A small read remains
complete. A large resource becomes its complete description plus a canonical block
index; retrieve complete blocks with:
```text
read "path"
--section "SECTION/Sub"
```
A folder whose listing does not fit the budget omits the entire listing atomically and
provides a copyable `contents` command. In addition, `max_folder_items` (config) cuts any
listing to the first N items and declares that limit; inspect the rest with native tools.
KaKeKiKoKu declares every omission; it never presents a fragment as if it were the complete
result.
## Writing knowledge
Preserve decisions, constraints, rationale, rejected alternatives, non-obvious gotchas,
and human intent. Do not archive routine edits or facts that are obvious from the code.
Contexts describe present truth, not a changelog. Rewrite an obsolete note instead of
stacking dated corrections. If a problem remains unresolved, document the diagnosis,
attempts, and rejected approaches before finishing, and explicitly tell the human.
Complete doctrine:
```text
help workflow
```
## Multi-project scope
One command works within one project. With one project open, `--project` may be omitted.
With multiple projects, single-project commands require it:
```text
read "src/auth.py"
--project "MyProject"
```
Only `search text`, `search structured`, `stats`, and `sync` can span every project, and
they must request that scope explicitly:
```text
search text "token refresh" --all-projects
stats --all-projects
sync --all-projects
```
Resources from different projects are never mixed within one command.
## Essential commands
```text
open list
read "path"
read "path"
--section "_description"
contents "folder/"
search text "query"
new "path"
--description "What it is and what it does."
edit set "path"
--section "_careful"
--content "Durable warning."
relation add "source"
--section "_careful"
--target "target"
--description "Reason for the dependency."
sync
```
## Web and product questions
The local Web and MCP share the same session and engine. Changes made through one
surface appear in the other. For questions about the product, the Web, or its
vocabulary:
```text
help kakekikoku
```
Current public information:
- https://kakekikoku.com/
- https://kakekikoku.com/docs
## Topic index
```text
help syntax Global grammar, quoting, options, empty blocks, and multi-project scope.
help kakekikoku Product, Web, human/AI collaboration, and vocabulary.
help workflow Operational workflow and capture doctrine.
help open Open, initialize, and discover projects.
help close Close a project from the session.
help read Read resources and block indexes.
help contents List a folder independently of its context.
help search Full-text, locate, and structured search.
help new Create contexts and entities.
help edit Content, structure, titles, and batches.
help relation Create, edit, remove, and inspect relations.
help sync Reconcile project and context.
help config Configuration and resource flags.
help schema Inventory of project sections.
help graph Incoming references to a resource.
help context Delete, clean, convert, rename, and rescue context.
help stats Knowledge metrics.
help view Cross-resource view of a section.
help backup Snapshots and restoration.
help format Physical `.wuniq` format and repair.
```
---help syntax# `help syntax` — Global syntax
## Canonical form
```text
<command> [<action>] ["<target>"] [--option "<value>"] [--flag]
```
Commands, actions, and options are lowercase. Compound words use `kebab-case`:
```text
remove-text
replace-range
set-title
--target-section
--all-projects
```
Paths, project names, sections, subsections, titles, content, queries, labels, patterns,
and values use double quotes.
## Quoting and escaping
A double quote inside a value is written as `\"` or `""`; both forms are valid. The
closing quote must be followed by whitespace: `--option="value"` is an error.
A command may span multiple lines: any whitespace, including line breaks, separates
tokens. The multiline examples in this help are valid commands as written.
Backslashes are never interpreted. Every value—paths, sections, project names, and prose
alike—is stored exactly as typed, so `C:\temp`, `C:\node_modules`, `\\server\share` and a
documented `\n` all survive verbatim. No doubling, no escaping.
Write multi-line content with a real line break inside the quotes:
```text
edit set "notes.entity"
--section "STEPS"
--content "First line.
Second line."
```
The one exception is the double quote itself, which the two forms above cover. Two traps
follow from that:
- A value ending in `\` escapes its own closing quote and swallows the rest of the
command. Drop the trailing separator or write the path with `/`.
- A carriage return, or any other control character except the tab, is refused on write:
a stray one makes Git treat the whole file as binary, so it stops being diffed, merged
and normalized.
## Options
Valid:
```text
--section "DECISIONS"
--project "MyProject"
```
Invalid:
```text
section="DECISIONS"
--section="DECISIONS"
```
Options belong to a specific signature. An unknown option produces an error and never
becomes a section name.
The sole exception to this shape is `search structured`, which places the unquoted
operators `equals` and `contains` as standalone words between quoted values
(help search).
## Flags
A flag does not take a value:
```text
--recursive
--index
--confirm
--all
--all-projects
```
## Lists
Repeat options or provide multiple operands:
```text
read "a.py" "b.py"
--section "_description"
read "architecture.entity"
--section "_careful"
--section "_rules"
```
Do not use CSV lists.
## Sections and subsections
The name is always a value:
```text
--section "section"
--section "title"
--section "PARENT/target"
```
Language keywords are valid section names because they occupy a different syntactic
position.
A name starts with a letter or `_` and continues with letters, digits, and `_`, with a
maximum of 40 characters per segment and a single `/`. An initial `_` belongs
exclusively to the private and reserved lists; a custom name starts with a letter.
Section selectors are case-insensitive: `"decisions"` finds `[DECISIONS]`, and two
blocks that differ only by case cannot coexist. Exact edit texts (`--old`, `--text`,
anchors) are case-sensitive.
## Content, structure, and metadata
Content:
```text
edit set
edit append
edit remove-text
edit replace
edit replace-range
edit clear
```
Structure:
```text
edit create
edit delete
edit rename
edit add-subsection
edit move
```
Metadata:
```text
edit set-title
edit clear-title
```
Only `edit delete` removes a section or subsection. `clear` empties the content while
preserving the block, title, and relations. If `remove-text` or `replace` removes all
text, the block remains empty.
## Empty blocks
An empty section may be structure prepared for the human, a title-only block, a block
with relations, or a pending field.
```text
edit create "planning.entity"
--section "QUESTIONS"
--title "Questions for the human to complete"
```
`_description` can never be empty.
## Multi-project scope
With one project open, `--project` is optional. With multiple projects, a
single-project command must select one:
```text
edit set "architecture.entity"
--section "DECISIONS"
--content "Content."
--project "MyProject"
```
Aggregators accept one of these options:
```text
--project "MyProject"
--all-projects
```
`--all-projects` is not allowed for commands that mutate resources or receive targets
belonging to a project.
## Errors
A syntax error must:
- Name the intent that could not be constructed.
- Identify the missing, unknown, or incompatible option.
- Show a copyable canonical form.
- Not expose tokenizer internals.
- Not execute a second possible interpretation.
---
Base guide and complete topic index: `help`help kakekikoku# `help kakekikoku` — Product and local Web
KaKeKiKoKu Studio is durable project memory shared by humans and AIs. It records the knowledge
that normally disappears between sessions: decisions, constraints, intent, rationale,
rejected alternatives, risks, relations, and non-obvious operational context.
KaKeKiKoKu is not a static context file. Knowledge is divided into blocks with identity,
indexed, related, read progressively, edited through the Web or MCP, and checked for
drift. It is not an AI skill and does not depend on any model or client.
## Locality, privacy, and ownership
The Knowledge Engine and Web run locally. Knowledge is stored as readable `.wuniq` text
alongside the project. KaKeKiKoKu requires no cloud account and sends no content, telemetry,
or analytics to a KaKeKiKoKu server.
KaKeKiKoKu owns the knowledge layer, not ordinary work with real files. The user and AI
continue using their IDE and native tools. Some explicit Web actions, such as creating a
Markdown file or duplicating a resource with its context, are conveniences requested by
the human, not automatic ownership of the project.
## Knowledge model
- File sidecar: context for a file.
- Folder sidecar: purpose, architecture, and rules for a folder.
- Entity: a cross-cutting decision, concept, policy, strategy, research topic, or roadmap.
- Section/subsection: a knowledge block with an optional title.
- Relation: a directed link between blocks.
- Project map: a navigable map of resources and descriptions.
- Sync: reconciliation between artifacts and knowledge.
States:
- Complete: resource and context both exist.
- Orphan: resource without context.
- Ghost: context without its original resource.
- Drift: the resource changed since its last synchronization.
Flags:
- Important: essential resource shown when opening.
- Pending: future work remains; the detail lives in a section.
- Draft: the knowledge is provisional.
Untracked and excluded are different. Untracked remains visible, but `sync` stops asking
for documentation. Excluded leaves KaKeKiKoKu's scope. KaKeKiKoKu rejects both transitions while
context still exists, so knowledge is never deleted silently.
## Human and AI
Web and MCP share a session. Context edited by the AI appears in the Web, and the
human's visual edits become available to the AI.
The human controls visibility through “Projects available to AI”. A hidden project may
remain open in the Web without appearing in normal AI discovery.
Precise means the human explicitly requests the operation in chat. Automatic depends on
the connected client supporting KaKeKiKoKu's interactive channel.
## Web map
Welcome:
- Choose the working directory.
- Open and create projects.
- Manage projects visible to AI.
- Enter the Learning Lab.
Menu:
- Open and create.
- Visibility.
- Global and project configuration.
- Backups.
- Clean export.
- Documentation and help.
- Quick slots 1–4 for temporary navigation.
Navigation:
- Project tree and context blocks.
- Knowledge and real-text search.
- Flags.
- Relations.
- Block movement.
- Read-only project map.
Central area:
- One collapsible block per section or subsection.
- Text and Markdown editing.
- Optional titles.
- Preview.
- Visual movements and relations.
- Text, code, document, and image views.
Sync/status:
- Broken relations.
- Drift.
- Pending documentation.
- Recent resources.
- Ghosts.
- Deterministic fixes.
- Document, untrack, or exclude.
## Common tasks
- Create context for a file or folder.
- Create a cross-cutting entity.
- Move blocks instead of copying them (`edit move` or Web).
- Relate dependencies with a useful reason.
- Search context and real text.
- Mark resources important, pending, or draft.
- Create consistent backups.
- Export a copy without `.wuniq` for publication (Web).
## Glossary
```text
context/sidecar A resource's `.wuniq` knowledge.
resource File, folder, or entity that owns a context.
block Section or subsection.
relation Dependency or directed link.
project map Project knowledge map.
parent link Immediate containing-folder context shown when reading (`context_parent`);
it does not include ancestor folders.
orphan/ghost Resource without context / context without resource.
drift Real resource changed since synchronization.
```
Current information:
- https://kakekikoku.com/
- https://kakekikoku.com/docs
- https://kakekikoku.com/docs/integrations/
- https://kakekikoku.com/docs/troubleshooting
- https://kakekikoku.com/docs/kakekikoku-format
Platforms, integrations, availability, pricing, and releases may change. For those
questions, consult the current public Web.
---
Base guide and complete topic index: `help`help workflow# `help workflow` — Operational workflow
## Proactive capture
Preserve durable decisions, constraints, rationale, rejected alternatives, non-obvious
gotchas, and human intent. Do not archive routine changes, small visual tweaks, or facts
obvious from the code unless they reveal a stable rule or trade-off.
Contexts describe present reality and its reasons; they are not changelogs. When a note
stops being true, rewrite it. Dates belong to genuine decisions, incidents, or historical
documents.
Useful signals:
```text
"We chose X because..." _whyNot or a decision section.
"Watch out for..." _careful.
"This must always..." _rules.
"The purpose is..." _soul.
"We still need to..." Section with the detail + pending flag.
```
To mark a resource pending:
```text
config add "pending" "roadmap.entity"
```
The flag does not store the task text.
Verify non-obvious claims against observed behavior. If a problem remains unresolved,
preserve the diagnosis, attempts, and rejected approaches before finishing, and
explicitly tell the human.
## Session workflow
1. Run `open list`.
2. Open only the necessary projects.
3. Read important resources and folder context before working in the area.
4. Inspect the real artifacts.
5. Use native tools for ordinary files.
6. Update context when durable knowledge changes.
7. Create the real file or folder before `new`; an entity does not need one.
8. Use `context delete` to remove context intentionally.
9. Rescue unique knowledge before deleting its only home.
10. Run `sync` after finishing the batch and resolve everything that remains.
## Knowledge distribution
- Folder sidecar: purpose, architecture, shared rules, workflows, and broad gotchas.
- File sidecar: function, constraints, failures, and local intent.
- Entity: cross-cutting decisions and concepts, policies, roadmaps, and research.
- Relation: explicit dependency between blocks, with the reason in its description.
## Multiple issues
Handle one at a time any issue that changes behavior, risks breakage, is not well
understood, or requires substantial work. Batch only safe, mechanical, fully understood
corrections.
## Quality
Prefer concise, complete blocks. Split by meaning, never mechanically, and never cut
knowledge merely to satisfy a limit. Use titles to clarify identifiers and relations to
make dependencies navigable.
---
Base guide and complete topic index: `help`help open# `help open` — Open and initialize projects
## Syntax
```text
open list
open "<absolute-project-path>"
[--description "<root-description>"]
[--recursive]
```
## Behavior
The specified folder must exist. KaKeKiKoKu does not create project directories or files: it
initializes only `.wuniq/config.yaml` and the root context if they are missing. The
operation is idempotent. It automatically reads the root when opening.
If the complete composition exceeds 30,000 characters, the project remains open but the
root read is omitted atomically. The response provides the exact `read` command; it
never returns a partial root. Reread the root at any time with `read "."`.
`--description` is required only when initializing a project without root context. The
text is preserved exactly; KaKeKiKoKu neither invents nor translates it. For an already
initialized project, the option is ignored: change the root description with `edit`.
A new project inherits the app's default content language. If none is set, write the
description in the user's language and configure it afterwards:
```text
config set "language" "en"
--project "myproject"
```
`--recursive` expands the initial listing within the configured budget.
## `open list`
Shows projects that are open and available to AI, each with its root description. That
description is the basis for opening only the projects the task needs. It shows at most
30 projects: open projects first, then closed projects in catalog order. If more exist,
it reports how many were omitted and directs the user to the Web catalog.
## Multi-project scope
Each `open` adds a project to the shared Web/AI session, up to a maximum of 20. Project
roots cannot be nested. Two different projects may contain identical relative paths;
select the scope with `--project`.
`--project` selects by root folder name, so two open projects cannot share that final
name. `open` rejects the conflict and explains how to resolve it.
To free a slot:
```text
close "C:/other-project"
```
## Examples
```text
open list
open "C:/myproject"
open "C:/myproject"
--description "Structured project memory."
open "C:/myproject"
--description "Structured project memory."
--recursive
```
---
Base guide and complete topic index: `help`help close# `help close` — Close a project
## Syntax
```text
close "<project-name-or-absolute-path>"
```
Removes the project from the session and releases its graph and read registry. It does
not delete or modify `.wuniq` files.
Accepts an open project name—the same name used by `--project`—or its absolute path. Open
project names are unique (`open` guarantees this), so a name always identifies one
project. Closing the last project returns the session to its initial state.
---
Base guide and complete topic index: `help`help read# `help read` — Read context
## Syntax
```text
read "<resource>" ["<resource>" ...]
[--section "<selector>" ...]
[--index]
[--recursive]
[--project "<project>"]
```
Examples:
```text
read "file.py"
read "folder/"
read "architecture.entity"
read "file.py.wuniq"
read "file.py"
--section "_careful"
--section "_rules"
read "file.py" --index
read "folder/" --recursive
read "a.py" "b.py"
--section "_description"
```
## Target rules
- `read "file.py"` reads only its context, not the real file.
- `read "file.py.wuniq"` is equivalent.
- `read "folder/"` combines context and listing if everything fits.
- `read "folder/folder.wuniq"` reads only context.
- `read "name.entity"` resolves an entity unless a real file or folder with that name
exists; `_type` remains the source of truth.
- An entity may live in a subfolder: `read "docs/decisions.entity"`.
- `read "."` reads the project root context.
## `--index` and `--recursive`
`--index` returns the description and canonical block index, without bodies. It is
incompatible with `--section` and requires existing context. It enables partial reads of
that resource for the rest of the session, and nothing else: choosing a section needs the
map, overwriting one needs the content.
`--recursive` applies to one folder and expands its listing into subfolders within the
budget.
## Read-state
Two permissions, not one. Reading a section requires knowing the structure; writing
requires having seen the content.
| Command | Partial reads | `edit`, `move`, `relation` |
|---|---|---|
| `read "path"` (complete) | yes | yes |
| `read "path" --section "_description"` | yes | yes |
| `read "path" --index` | yes | no |
The first read of each resource is complete by default. The `_description` selection is
the minimal exception and is always allowed; `new` registers the created resource as read.
`--index` is the cheap way to open a large resource: one call returns every selector with
its size, and the sections you pick can be read straight away. To edit afterwards, read
the content first — an index shows what exists, never what an edit would replace.
Multiple targets are allowed only with one `_description` selection. They all belong to
the same project, preserve input order, and report item-local errors without canceling
the others.
The batch registers read-state only if the complete response fits. If it exceeds 30,000,
no item is registered; repeat with fewer targets.
## Progressive delivery
A complete resource that fits is returned unchanged. If it exceeds the budget, KaKeKiKoKu
returns:
- Complete `_description`.
- Complete canonical index.
- `context_parent`.
- Bounded `referenced_by` guidance.
The index includes empty blocks and relation-only blocks. Each row shows the exact
selector, character count, relation count, and number of subsections.
Selecting a parent returns its body and children when they fit. Otherwise, it returns the
complete parent and the complete child index. A subsection is an atomic leaf and is never
truncated.
If a multi-selection does not fit, KaKeKiKoKu returns only the complete selection index and
asks for smaller groups; it does not return the first subset.
## Folders
A folder keeps context + listing only if the complete response fits. Otherwise, it omits
the entire listing and provides a command:
```text
contents "folder/"
```
## Relations and computed zones
Relations appear at the start of each block read.
Computed zones:
```text
-- computed --
context_parent
referenced_by
-- contents --
```
`context_parent` is only the immediate containing folder. It is not inherited and does
not include ancestor folders.
## Missing resources
- File or folder without context: suggests `new`.
- Nonexistent resource: diagnosed before read-state.
- Nonexistent entity: may be created directly with `new`.
- Ghost with a surviving sidecar: remains readable.
---
Base guide and complete topic index: `help`help contents# `help contents` — List a folder
## Syntax
```text
contents "<folder>"
[--recursive]
[--project "<project>"]
```
The target must be an existing folder; `contents "."` lists the project root. The
response has its own 30,000-character budget.
Each depth level is atomic: descriptions for the entire layer when they fit; otherwise,
names only for that layer and subsequent layers. Within a folder, the order is:
1. Important folders.
2. Important files/entities.
3. Folders with context.
4. Folders without context.
5. Files/entities with context.
6. Files without context.
Depth takes precedence over priority. A deeply nested important item does not displace a
higher layer.
Each visible entry appends its active status labels inline: `[important]`, `[pending]`,
`[draft]`, and `[untracked]`. Labels may coexist and are included in response-budget
measurement.
If even level zero does not fit as names, complete lines are included by priority and
the number missing is reported. There is no pagination.
`contents` does not read or unlock the folder context. To retrieve omitted items:
- Use native file tools to select relevant paths efficiently, then batch-read their KaKeKiKoKu
descriptions in one call:
```text
read "path1" "path2" --section "_description"
```
- Run `contents` on a child folder when the omitted items are below it.
---
Base guide and complete topic index: `help`help search# `help search` — Search knowledge and text
## Syntax
```text
search text "<query>"
[--project "<project>" | --all-projects]
search locate "<text>"
--in "<resource>"
[--project "<project>"]
search structured
--match "<section>" equals "<value>" ["<value>" ...]
[--match "<section>" contains "<value>" ["<value>" ...] ...]
[--project "<project>" | --all-projects]
```
## Full-text search
Searches resource names, section/subsection identifiers and titles, `_description`,
reserved and custom section content, paths, and real file content.
Exact-match weights (partial matches score less):
```text
name 15
_description 12
section identifier 5/4 (reserved/custom)
reserved 5
custom 4
path 4
real content 4 (cumulative maximum 14 per resource)
```
The query is split on spaces and every token must appear (AND). Matching is
case- and diacritic-insensitive, so `"autenticacion"` finds `"autenticación"`. It uses
substrings, not whole words: `"cat"` may match `"application"`. There is no exact
phrase search; to locate literal text containing spaces, use `search locate`. Recent
resources receive a boost. A result snippet is taken from the field or block that
actually scored and is centered on the most specific matching token.
## Locate
```text
search locate "TODO"
--in "roadmap.entity"
```
Finds matching lines and context blocks within one resource. It always operates in one
project.
Searches the real file content (if it is text and reasonably sized; every omission is
declared) and its `.wuniq` context. File results are one hit per matching line; context
results are one hit per matching section or subsection, not per textual occurrence.
## Structured search
```text
search structured
--match "_type" equals "entity"
search structured
--match "_type" equals "entity"
--match "_description" contains "API" "REST"
```
- `equals` matches the complete value or an item in a comma-separated list.
- `contains` is a substring match.
- Neither is case- or diacritic-sensitive.
- Multiple `--match` clauses use AND.
- Multiple values in one `--match` use OR.
- Searches private fields and top-level sections (reserved and custom); it does not
search subsections.
- `equals` and `contains` are unquoted lowercase standalone words.
Flags store `true`; use this to enumerate flagged resources:
```text
search structured
--match "_pending" equals "true"
```
## Limits
The normalized expression allows 2,000 UTF-16 characters; `--project` and the path from
`--in` do not count.
MCP:
- 25 full-text candidates per project.
- 100 structured candidates per project.
- 50 locate occurrences.
- If output exceeds 30,000, it delivers complete blocks, declares omissions, and does
not paginate.
- Multi-project delivery uses rounds so one project cannot consume everything.
Web:
- Up to 500 global results.
- Initial render of 100, followed by local chunks.
- No MCP text budget.
With multiple projects, `search text` and `search structured` require `--project` or
`--all-projects`.
---
Base guide and complete topic index: `help`help new# `help new` — Create context or entities
## Syntax
```text
new "<resource>"
--description "<description>"
[--set "<section>" "<content>" ...]
[--create "<section>" ...]
[--project "<project>"]
```
Examples:
```text
new "src/auth/AuthService.cs"
--description "Manages OAuth2 and the token lifecycle."
new "src/auth/"
--description "Authentication and authorization module."
new "decisions.entity"
--description "API architecture decisions."
new "planning.entity"
--description "Planning structure shared with the human."
--create "QUESTIONS"
--create "DECISIONS"
--set "STATUS" "In design"
```
## What it creates
KaKeKiKoKu detects the type:
- Real file: file-sidecar.
- Real directory: folder-sidecar.
- `.entity` suffix without a real file or folder: standalone entity.
- Existing sidecar: `_type` governs classification.
Create ordinary files and folders first with native tools. An entity needs no physical
resource and may live in an existing subfolder:
`new "docs/decisions.entity"`.
## Initial sections
`--description` creates `_description` and is required, with 10–280 characters.
`--set` creates a block with content:
```text
new "architecture.entity"
--description "Current product architecture."
--set "_careful" "Do not break format compatibility."
--set "section" "A custom section named section."
```
`--create` creates an empty section or subsection:
```text
new "planning.entity"
--description "Template for the human to complete."
--create "QUESTIONS"
--create "QUESTIONS/Compatibility"
```
Rules:
- The same section cannot appear in both `--set` and `--create`.
- `_description` is set only through `--description`.
- Private sections cannot be created.
- Every section is validated before writing.
- The complete creation is atomic.
- The resource is registered as read.
- Neither `--set` nor `--create` takes a title; add one later with `edit set-title`.
The English NOTE asking you to complete documentation appears only when the newly written
context contains `_description` and no other section. This applies to folders, entities,
and files created during the session. A file that already existed before the project was
opened does not show it (its bulk documentation is governed by `sync`).
## Common errors
- Context already exists: use `edit`.
- File not found: create the real file or folder first.
- Description too short/long: adjust `_description`.
- Excluded resource: remove the exclusion pattern first.
- Missing project: with multiple projects, add `--project`.
---
Base guide and complete topic index: `help`help edit# `help edit` — Edit blocks
`edit` modifies content, structure, and metadata. It requires the resource to have been
read in the current session, at least through `_description`.
## Content
### Set
```text
edit set "<resource>"
--section "<section>"
--content "<content>"
[--project "<project>"]
```
Creates the block if it does not exist and replaces all its content if it does:
```text
edit set "architecture.entity"
--section "DECISIONS"
--content "We chose JWT because it is stateless."
```
An empty string is rejected. To preserve the block while empty, use `edit clear`; to
remove it, use `edit delete`.
### Append
```text
edit append "<resource>"
--section "<section>"
--content "<content>"
[--project "<project>"]
```
Adds a line to the same block. If the block does not exist, it creates it:
```text
edit append "architecture.entity"
--section "DECISIONS"
--content "We added refresh-token rotation."
```
Do not confuse this with `add-subsection`: `append` extends the same block;
`add-subsection` creates a new child block.
### Remove exact text
```text
edit remove-text "<resource>"
--section "<section>"
--text "<exact-text>"
[--project "<project>"]
```
Removes every exact occurrence. If no text remains, it preserves the section, its title,
and its relations.
### Replace one match
```text
edit replace "<resource>"
--section "<section>"
--old "<old-text>"
--new "<new-text>"
[--project "<project>"]
```
Requires exactly one match. Zero matches produces a diagnosis and suggestion; more than
one requires disambiguation.
```text
edit replace "src/api.py"
--section "_description"
--old "REST"
--new "GraphQL"
```
`--new ""` may remove the matching text, but it does not remove the structure.
### Replace a range
```text
edit replace-range "<resource>"
--section "<section>"
--start "<start-anchor>"
--end "<end-anchor>"
--content "<replacement>"
[--project "<project>"]
```
Replaces from the start of the start anchor through the end of the end anchor, inclusive.
The start anchor must appear exactly once in the block; the end anchor is searched after
the start anchor, and its first occurrence is used. If either is missing, the command
returns an error with a diagnosis.
### Clear content
```text
edit clear "<resource>"
--section "<section>"
[--project "<project>"]
```
Deliberately empties the block. It preserves:
- Identifier.
- Title.
- Outgoing relations.
- Incoming relations.
- Structural position.
Not allowed on `_description`.
## Structure
### Create an empty block
```text
edit create "<resource>"
--section "<section>"
[--title "<title>"]
[--project "<project>"]
```
Use it to prepare structure for the human, create a title-only block, or reserve a block
that will receive relations:
```text
edit create "planning.entity"
--section "QUESTIONS"
--title "Questions to complete with the human"
```
It also creates named subsections:
```text
edit create "planning.entity"
--section "QUESTIONS/Integrations"
--title "Integrations to review"
```
If a subsection's parent is missing, it is created empty. `create` fails if the block
already exists.
### Delete a block
```text
edit delete "<resource>"
--section "<section>"
[--project "<project>"]
```
This is the only `edit` operation that removes structure. Deleting a section also
deletes its subsections. The operation transactionally updates exact incoming relations
and reports the relations that lived inside it.
`_description` cannot be deleted.
### Rename
```text
edit rename "<resource>"
--section "<old-name>"
--new-name "<new-name>"
[--project "<project>"]
```
Examples:
```text
edit rename "architecture.entity"
--section "Ideas"
--new-name "DECISIONS"
edit rename "architecture.entity"
--section "DECISIONS/Auth"
--new-name "DECISIONS/Authentication"
```
The rename is local to the resource, preserves the block's content, title, and identity,
and updates exact incoming relations in the same transaction. Names are case-insensitive,
so a case-only change is not a rename. Reserved sections cannot be renamed.
### Auto-numbered subsection
```text
edit add-subsection "<resource>"
--parent "<parent-section>"
[--title "<title>"]
[--content "<content>"]
[--project "<project>"]
```
KaKeKiKoKu generates `S_001`, `S_002`... using maximum + 1. This is intended for logs,
journals, or append-only entries where a human-readable identifier adds no value.
Requires at least a title or content:
```text
edit add-subsection "journal.entity"
--parent "ENTRIES"
--title "Load test"
--content "Result: 120 ms. Environment: local."
```
For a topic that must be referenced, retitled, or edited again, use a named subsection
with `set` or `create`.
### Move a block
```text
edit move "<resource>"
--section "<selector>"
[--target "<target-resource>"]
[--target-parent "<parent-section>"]
[--confirm]
[--project "<project>"]
```
Relocates a section or subsection within the resource or to another resource while
preserving identity, title, subsections, and relations; incoming references migrate
automatically. Without `--target`, the move is internal. `--target-parent`—an existing
section in the destination—places it as a subsection; without it, the block becomes a
top-level section.
Without `--confirm`, the command only returns the plan—verdict, final name, writes, and
migrations—and writes nothing. Execution requires repeating it with `--confirm` after
reading the source, destination, and contexts with incoming references to the moved
block; the command lists any missing reads. A name conflict does not block the move: it
is resolved with a `_2`, `_3` suffix and reported. `move` has no batch clause.
## Titles
```text
edit set-title "<resource>"
--section "<section>"
--title "<title>"
[--project "<project>"]
edit clear-title "<resource>"
--section "<section>"
[--project "<project>"]
```
The title is the visible description next to the block name. It changes neither the
identifier nor the content. It must be one line, contain no brackets, and have at most
100 characters.
An empty string is rejected; remove the title with `clear-title`.
## Atomic batch
```text
edit batch "<resource>"
<mutation-clause>...
[--project "<project>"]
```
Clauses:
```text
--set "<section>" "<content>"
--append "<section>" "<content>"
--remove-text "<section>" "<exact-text>"
--replace "<section>" "<old-text>" "<new-text>"
--replace-range "<section>" "<start>" "<end>" "<replacement>"
--clear "<section>"
--create "<section>"
--delete "<section>"
--rename "<old-name>" "<new-name>"
--set-title "<section>" "<title>"
--clear-title "<section>"
```
Example:
```text
edit batch "planning.entity"
--create "QUESTIONS"
--set-title "QUESTIONS" "Questions for the human"
--set "STATUS" "Under review"
--append "_careful" "Do not publish before finalizing the syntax."
```
Each clause carries all its operands, in a fixed number. Order is semantic. Everything
is validated before committing, and the batch is written atomically. A clause never
inherits data from the preceding clause.
Because operands are fixed, `--create` does not take a title (add it with a later
`--set-title` clause), and `add-subsection`, whose operands are optional, has no batch
clause: run it as an individual command.
## Relations
Manage relations with `relation`. Replacing or clearing content does not remove the
block's relations.
## Rules
- Read-before-edit is mandatory (at least `_description`). Having read only the `--index`
is not enough: it grants partial reads, never a write (help read).
- Paths, selectors, and content are quoted.
- Custom names start with a letter and continue with letters, digits, and `_`. A name
starting with `_` is valid only if it is reserved; unknown ones are rejected.
- A selector allows a single `/`.
- Selectors are case-insensitive; exact texts (`--old`, `--text`, anchors) are
case-sensitive.
- Private sections are not editable.
- `_description`: 10–280 characters and never empty.
- Each block: maximum 4,000 characters.
- Resource: maximum 30 top-level sections and 60 subsections.
- A legacy resource that exceeds the current limits remains editable only through edits
that reduce its size.
- Values accept real line breaks and store backslashes verbatim; nothing is unescaped
(help syntax). Control characters other than the newline are refused on write.
- Atomic writes preserve the hash captured at the start of each edit command and fail if
the sidecar changes during that command. They do not detect changes made between an
earlier `read` and the later edit; reread when concurrent human or agent edits are
possible.
## Names that must work
All of these are valid data:
```text
"section"
"title"
"target"
"to"
"old"
"new"
"description"
"fields"
"sections"
"project"
"append"
"remove"
"set"
"rename"
```
---
Base guide and complete topic index: `help`help relation# `help relation` — Manage relations
Requires a prior read of the source resource.
## Syntax
```text
relation list "<source>"
[--project "<project>"]
relation add "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
[--description "<description>"]
[--project "<project>"]
relation remove "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
[--project "<project>"]
relation set-description "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
--description "<description>"
[--project "<project>"]
relation clear-description "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
[--project "<project>"]
```
## Behavior
Relations connect blocks and form a knowledge graph. On disk, targets are stored as UUIDs
so relations survive moves and renames.
Use logical resource paths in normal commands. For recovery, `--target` also accepts the
UUID of an existing sidecar in the selected project; invented and cross-project UUIDs are
rejected.
`list` shows the target, optional target section, and description. If a stored UUID no
longer resolves, read/list surfaces preserve the repair handle as
`[BROKEN_REFERENCE: <uuid>]`.
`add` resolves the target resource and adds the relation to the source block:
```text
relation add "src/auth/AuthService.cs"
--section "_careful"
--target "config.py"
--target-section "SECRETS"
--description "Do not cache these values."
```
`remove` identifies the relation by its address, without using the description.
`set-description` changes only the description. Changing the target or target section
requires remove + add.
`clear-description` preserves the relation and removes its description.
## Identity
A relation is identified by:
```text
source resource
source section
target resource
optional target section/subsection
```
One block cannot contain two relations to the same address. Relations to different
sections of the same resource are distinct.
## Rules
- The target must have context and a UUID.
- The source section must exist, even if it is empty.
- If a target section or subsection is provided, it must exist in the target sidecar
when saving.
- Source and target belong to the same project.
- The description allows neither brackets nor line breaks.
- Relations are independent from normal text.
- `edit set`, `edit clear`, and other content changes preserve them.
- Use `graph` to see incoming relations.
- Use `read` to see outgoing relations inline.
- Cross-project relations are not allowed. Mention the other project as ordinary text
when necessary.
When a block depends on a source of truth, use a relation and explain why. Do not leave
that dependency only as a textual mention.
---
Base guide and complete topic index: `help`help sync# `help sync` — Reconcile project and context
## Syntax
```text
sync
[--project "<project>" | --all-projects]
sync ack "<resource>" ["<resource>" ...]
[--project "<project>"]
```
With one project open, the scope may be omitted. With multiple projects, `sync` requires
`--project` or `--all-projects`. All `sync ack` targets belong to the same project.
## What it does
`sync` is the context compiler. It scans the complete project, detects
desynchronization, applies safe deterministic fixes, and presents work that requires a
decision.
It detects:
- Complete Git conflict blocks in `.wuniq`.
- Recent undocumented resources.
- Pre-existing pending documentation.
- Ghost sidecars.
- Content drift.
- Broken relations.
- References to deleted sections.
- Empty required fields, including sections that structurally exist.
- Malformed YAML.
- Duplicate UUIDs.
An auto-fix is applied only when there is one safe solution:
- Folder sidecar with a misaligned name.
- Ghost and orphan with one unambiguous hash match.
- Other purely deterministic reconciliations.
## Git conflicts
KaKeKiKoKu recognizes a conflict as a complete, ordered block starting in column 1:
```text
<<<<<<<
=======
>>>>>>>
```
All three markers use the same minimum width of seven characters. Diff3 is supported.
Isolated markers or similar text inside prose do not block.
A conflicted `.wuniq` blocks `sync` for its project and quarantines that file. In
`sync --all-projects`, the other projects continue.
While blocked:
- The conflicted resource disappears from the tree and searches, and its `read`, `edit`,
and write operations are rejected with rescue guidance.
- The rest of the project remains operational; the last valid index and graph remain in
memory and may become stale until the conflict is resolved and sync runs.
- An operation that needs to rewrite the conflicted file fails without saving.
Rescue exception:
1. Use native tools only on each exact `.wuniq` file reported.
2. Run `help format`.
3. Resolve every block while preserving UUID, sections, relations, and non-conflicting
knowledge.
4. Ask the human if merge intent is ambiguous.
5. Do not stage or commit without an explicit request.
6. Run `sync` again.
## Severity
- Error: compromises integrity and must be resolved.
- Warning: possible problem worth reviewing.
- Info: auto-fix applied by that run or an improvement suggestion.
The built-in `_description` invariant is Error. Additional `required_fields` configured
by a project are documentation preferences and are Warning when missing.
Pending documentation has its own block and does not inflate the Info count.
## Pending documentation
A resource without context is classified by time:
- Recent: created or modified in this session. Individual
`Recent undocumented resource` warning.
- Pre-existing: existed before the project was opened. Enters the
`PENDING DOCUMENTATION` batch, shown in groups of `max_sync_report_items`.
If one run accumulates more recent resources than `max_sync_report_items`, all of them
move to the pending batch to avoid overwhelming the AI.
When the total pending count exceeds a threshold (25), the batch is hidden and the
summary declares it in one line: the human decides on bulk onboarding by enabling
processing from the Web sync panel. The AI must not document that batch on its own
initiative; `stats` always shows real coverage.
## MCP budget
If the output fits within 30,000 characters, it is preserved. Otherwise:
- Complete issues are delivered.
- Unresolved errors take priority.
- `... and X more issue(s)` is reported.
- A path or suggestion is never cut.
- There is no pagination.
Resolve what is shown and repeat `sync`; it always recalculates current state.
The Web panel preserves the complete typed result. “Analyze + AI” is AI delivery and
uses the same atomic cutoff.
## Drift
When the context remains accurate:
```text
sync ack "src/auth.py" "src/helpers.py"
```
When the change introduces decisions, rules, intent, or gotchas, document those first
and then acknowledge the drift.
An exceptionally large `sync ack` may persist some acknowledgments before cutting its
response. Do not blindly repeat the original batch; run `sync` to learn the remaining
state.
## Multiple issues
Handle one at a time the issues that:
- Change behavior.
- Risk breakage.
- Are not fully understood.
- Require substantial work.
Batch only safe, mechanical work.
## Untracked, excluded, and the Web panel
To keep a resource visible while stopping context requests:
```text
config add "untracked" "path"
```
To hide it completely:
```text
config add "excluded" "path"
```
In the Web panel:
- Dismiss is equivalent to untracked and is persistent.
- Exclude is equivalent to excluded.
- The robot button delegates the item to the AI.
---
Base guide and complete topic index: `help`help config# `help config` — Configuration and flags
## Syntax
```text
config show
[--project "<project>"]
config set "<key>" "<value>"
[--project "<project>"]
config add "<collection>" "<item>" ["<item>" ...]
[--project "<project>"]
config remove "<collection>" "<item>" ["<item>" ...]
[--project "<project>"]
```
With multiple projects, `--project` is mandatory.
## Scalar values
```text
"language"
"max_folder_items"
"max_sync_report_items"
```
Examples:
```text
config set "language" "en"
config set "max_folder_items" "300"
--project "MyProject"
```
`max_folder_items` limits any resource listing: folders, `graph`, and `view`.
## `config.yaml` collections
```text
"excluded"
"untracked"
"required_fields"
```
Examples:
```text
config add "untracked" "*.tmp" "*.spec.js"
config add "excluded" "node_modules" ".git" "dist"
config add "required_fields" "_description" "_careful"
config remove "excluded" "dist"
```
Missing entries from project-configured `required_fields` are sync Warnings. The
built-in `_description` requirement remains an integrity Error.
## Resource flags
They are also managed with `config add/remove`, but are stored in the sidecar:
```text
"important"
"pending"
"draft"
```
```text
config add "important" "architecture.entity"
config add "pending" "roadmap.entity"
config remove "draft" "research.entity"
```
The three flags are independent and may coexist. `pending` does not store the task
detail; write it in a knowledge block. Flags do not require a prior resource read.
Never edit `_important`, `_pending`, or `_draft` directly. To enumerate flagged
resources:
```text
search structured
--match "_pending" equals "true"
```
## Excluded versus untracked
Excluded:
- Resource is invisible.
- No sidecar.
- Outside sync and the tree.
- Suitable for artifacts, secrets, and IDE files.
Untracked:
- Resource remains visible.
- Does not need a sidecar.
- Sync does not report it.
A resource cannot belong to both. Remove it from the current collection first.
If a pattern reaches resources that still retain context, the add is rejected and lists
them: remove that context first with `context delete`. An add with no new entries
responds `No new entries to add` with the item-local reason.
## Patterns
```text
"Program.cs" File at any depth.
"docs/spec.md" Exact relative path.
"node_modules/" Folder with this name.
"wwwroot/lib/" Folder sequence.
"**/secrets/**" Folder at any depth.
"*.tmp" Extension.
".env.*" Dotfile prefix.
"appsettings*.json" Name wildcard.
"wwwroot/*.png" Wildcard within one segment.
"docs/*/index.md" Wildcard per segment.
```
## YAML and delivery
KaKeKiKoKu writes values and lists with YAML single quotes. The reader continues accepting
legacy unquoted or double-quoted values. The first explicit open normalizes lists managed
by KaKeKiKoKu and reports the diff.
`config show` returns the complete raw YAML if it fits. If it exceeds 30,000, it fails
without a fragment and directs the user to the Web panel.
---
Base guide and complete topic index: `help`help schema# `help schema` — Section vocabulary
## Syntax
```text
schema list
[--project "<project>"]
```
Shows the actual top-level section vocabulary. Reserved sections come first in canonical
order; custom sections follow, ordered by frequency. The output is one flat list. It
helps reuse conventions instead of creating nearly duplicate names.
Subsections are local details and are not aggregated. Read them in their resource:
```text
read "architecture.entity"
--section "DECISIONS"
```
`schema` is read-only. There is no global rename or delete. After reading the specific
resource:
```text
edit rename "architecture.entity"
--section "Old"
--new-name "New"
edit delete "architecture.entity"
--section "Obsolete"
```
---
Base guide and complete topic index: `help`help graph# `help graph` — Incoming references
## Syntax
```text
graph "<resource>"
[--project "<project>"]
```
Shows every relation whose source block points to the target: who references the target,
the source block, the addressed target block, and the relation description. Several
relations between the same two resources remain separate. See outgoing relations with
`relation list` or inline in `read`.
The target must have context and identity. A physical resource without a sidecar and a
nonexistent path are not nodes. A ghost remains queryable while its sidecar survives.
## MCP delivery
If paths and descriptions fit, the complete output is returned. Otherwise:
1. All descriptions are omitted as one layer.
2. The complete uniform path index selected by
`max_folder_items` is preserved.
3. If even the minimal index does not fit, a controlled failure directs the user to the
Web.
Graph scans the complete project first, so it reports the exact number of relations
excluded by `max_folder_items`.
---
Base guide and complete topic index: `help`help context# `help context` — Context lifecycle
## Syntax
```text
context clean "<ghost-resource>"
[--confirm]
[--project "<project>"]
context clean
--all
[--confirm]
[--project "<project>"]
context delete "<resource>"
[--confirm]
[--project "<project>"]
context convert "<ghost-resource>"
[--name "<name.entity>"]
[--confirm]
[--project "<project>"]
context rename "<entity>"
--name "<new-name.entity>"
[--confirm]
[--project "<project>"]
```
## Intents
`clean`:
- Deletes one specific ghost.
- With `--all`, deletes every ghost in the project.
- Rejects resources that still exist.
`delete`:
- Deletes context from a live file or folder, leaving it orphaned.
- Legitimately deletes an entity.
- Cleans incoming references by UUID if no other context with that identity survives.
- Rejects ghosts.
`convert`:
- Converts a ghost into an entity.
- Preserves UUID and incoming relations.
- Without `--name`, keeps the historically derived name.
- With `--name`, chooses the final logical `*.entity` name within the same folder.
- Validates the name and collision before writing directly to the final destination.
- Rejects resources that still exist.
`rename`:
- Renames an entity within the same folder.
- Preserves UUID, incoming relations, and read-state.
- Entities only: rename a real file or folder with native tools, then `sync` realigns
its sidecar by hash.
Without `--confirm`, lifecycle commands return a read-only preflight and write nothing.
`context delete` includes sidecar size, non-empty blocks, outgoing relations, incoming
relation impact, and the exact confirmation command. Repeat with `--confirm` to mutate.
Bulk cleaning additionally requires `--all`.
## Ghost paths
Use the original logical path:
```text
context clean "src/old/deleted.py" --confirm
```
Do not use the physical `.wuniq` name.
## Moved or renamed files
1. Move or rename the file with native tools.
2. Run `sync`.
3. If the hash match is unambiguous, sync realigns the sidecar, and the run that applies
it reports an auto-fix.
4. If the file also changed, sync shows the ghost and orphan separately.
In an ambiguous case:
- Clean the ghost and create new context, or
- Move the sidecar natively together with the resource and run sync.
Moving or renaming the sidecar together with its resource is the only ordinary native
operation allowed on `.wuniq`. Never edit its content natively except to rescue
corruption or resolve a complete Git conflict.
## Intentional deletion
Use `context delete`; do not delete the sidecar natively. Before removing the only home
of a decision, pending item, or proposal, relocate that knowledge.
## Common errors
- No context found.
- Is a ghost: use clean or convert.
- Not a ghost: clean/convert do not apply.
- Resource still exists: clean is rejected.
- Entity already exists: convert cannot overwrite it.
---
Base guide and complete topic index: `help`help stats# `help stats` — Project metrics
## Syntax
```text
stats
[--project "<project>" | --all-projects]
```
Shows:
- Files and folders.
- Context coverage.
- Entity count.
- Sections in use.
- Structural shape of context based on the number of non-empty sections.
- Latest sync result.
- Session state.
The structural classification (2+ sections, 1 section, or none) measures formal
coverage, not semantic quality or whether knowledge is current.
With multiple projects, it requires `--project` or `--all-projects`.
---
Base guide and complete topic index: `help`help view# `help view` — Cross-resource view
## Syntax
```text
view "<folder>"
--section "<section>"
[--recursive]
[--project "<project>"]
```
Reads the same selector from every context in a folder and presents the blocks side by
side:
```text
view "src/"
--section "_careful"
view "src/"
--section "_rules"
--recursive
```
Works with reserved sections, custom sections, parents with subsections, and direct
`PARENT/Child` selectors.
## Read-state
`view` is a read-only aggregate and does not register each resource individually. Before
editing a result:
```text
read "resource"
--section "SELECTOR"
```
## MCP delivery
The cross-resource selection is one logical unit:
- If it fits, it returns every body.
- Otherwise, it does not deliver a first batch: it returns a complete candidate index.
- Each row includes a copyable `read` command and metadata.
- Titles are omitted as a complete layer if necessary.
- Sizes may then be omitted, but never recovery commands.
- If even the minimal index does not fit, it fails and asks for a more specific folder
or selector.
It respects excluded and `max_folder_items`. If it reaches the limit, it reports that
the total is at least N and that the index may not cover the complete scope.
---
Base guide and complete topic index: `help`help backup# `help backup` — Snapshots
## Syntax
```text
backup list
[--project "<project>"]
backup create
--label "<label>"
[--project "<project>"]
backup restore
--snapshot "<snapshot-id>"
[--confirm]
[--project "<project>"]
```
With multiple projects, `--project` is mandatory.
## List
Shows every project snapshot, newest first:
- Snapshot ID.
- UTC date and time.
- Origin.
- Files copied.
- Files skipped.
- Label.
The MCP list is atomic. If it exceeds 30,000, it returns no partial rows and directs the
user to the Web.
## Create
```text
backup create
--label "before-auth-rewrite"
```
The label allows up to 80 UTF-16 characters. The snapshot uses a UTC timestamp and a
sanitized label:
```text
2026-03-18_143022_1234567Z_before-auth-rewrite
```
The copy is incremental. A labeled snapshot is preserved even if it copies no files,
because it marks a reference point.
## Restore
```text
backup restore
--snapshot "2026-03-18_143022_1234567Z_before-auth-rewrite"
```
Without `--confirm`, returns a read-only preflight split into files that would be
overwritten, files that would be created, and current `.wuniq` UUID carriers that would
be deleted, plus the exact confirmation command. UUID collisions show the UUID, the
snapshot path that wins, and every conflicting current carrier. It writes nothing.
Repeat with `--confirm` to rebuild that preflight and apply it transactionally. The
snapshot is authoritative for KaKeKiKoKu identity: if it restores UUID U at one path, a
current `.wuniq` carrier of U at another path is deleted. Other files created later
remain untouched, so restore is not a complete filesystem mirror. A snapshot that
itself contains U at several paths is rejected because it has no unique winner. In
incremental snapshots, restore searches backward for the actual content.
It verifies everything before writing, rolls back on failure, reloads configuration, and
refreshes the project.
## Rules
- App configuration controls automatic snapshots on open.
- Manual and AI snapshots remain available when automatic snapshots are off.
- Captures readable, non-excluded project files up to 50 MB—including code, not only
`.wuniq`.
- Large or unreadable skipped files are recorded and cannot be restored.
- Unlabeled automatic/manual snapshots with no changes are not created.
- Retention: 1–100 copies; maximum days is independent.
- Snapshots live in KaKeKiKoKu user data, under `backups/<project-slug>/`, outside the
project. The storage location cannot contain a project or live inside one.
---
Base guide and complete topic index: `help`help format# `help format` — The `.wuniq` format
The physical format has compatibility major version 1. Real sidecars stamp
the full KaKeKiKoKu product version in `[_version]`; the major version is the compatibility
boundary. This reference helps understand, rescue, or repair context; it does not
authorize ordinary native editing.
## Types
```text
file-sidecar filename.ext.wuniq
folder-sidecar folder/folder.wuniq
entity name.entity.wuniq
```
## Structure
The four categories below classify blocks; they are not serialization order:
- Private fields: closed system list.
- Reserved sections: closed knowledge list.
- Custom sections `[AnyName]`: start with a letter, never `_`.
- Subsections `[PARENT/Child]`.
Private fields are written first. Subsections appear after their parent. Reserved and
custom sections preserve creation order.
## Private fields
```text
[_version]
[_uuid]
[_type]
[_content_hash]
[_file_size]
[_file_mtime]
[_modified_at]
[_important]
[_pending]
[_draft]
```
They are managed by KaKeKiKoKu. Modify flags through `config add/remove`.
## Reserved sections
```text
[_description] Required; 10–280 characters.
[_summary] Synthesis for whoever arrives.
[_conclusions] Learnings and decisions.
[_does] Functionality.
[_rules] Invariants.
[_careful] Risks and gotchas.
[_whyNot] Rejected alternatives.
[_soul] Essential reason.
[_guide] How to work with the resource.
```
## Headers and titles
```text
[name]
[name: Human-readable title]
[PARENT/Child]
[PARENT/Child: Title]
```
The title is cosmetic. References use only the identifier.
```text
edit set-title "path"
--section "DECISIONS"
--title "Architecture Decision Log"
edit clear-title "path"
--section "DECISIONS"
```
## Empty blocks
The format allows headers without content. MCP syntax explicitly creates or preserves
them:
```text
edit create "path"
--section "QUESTIONS"
edit clear "path"
--section "QUESTIONS"
```
Only `edit delete` removes the block.
## Relations
On disk, they appear at the start of the block:
```text
wuniq: target-resource
wuniq: target-resource: description
wuniq: target-resource[Section]
wuniq: target-resource[Section/Sub]: description
```
Physical targets are UUIDs. In commands, each component is provided separately:
```text
relation add "source"
--section "_careful"
--target "target-resource"
--target-section "Section/Sub"
--description "Reason"
```
Do not write `wuniq:` lines with `edit`.
## Limits
```text
Prose per resource 52,000 characters.
Content per block 4,000 characters.
_description 10–280 characters.
Title 100 characters.
```
Relations do not count as prose. These limits express cognitive atomicity: if a block
does not fit, redistribute it by meaning; do not cut knowledge.
## Format rules
- Blocks are separated by a blank line.
- UTF-8; BOM is managed.
- All content uses the configured language.
- Prose is concise, complete, and scan-friendly.
- A content line cannot look exactly like a KaKeKiKoKu header, even with leading whitespace.
- Put such an example inside a sentence or as inline code.
- `variable[10]`, inline mentions, and Markdown links remain valid.
- The legacy escape `\[NAME]` is tolerated only for rescue; sync reports it and saves are
blocked until the line is rewritten.
- Only one subsection level is allowed.
## Conceptual example
The example abbreviates `[_version]` to the compatibility major. It is not a literal
replacement value for a healthy sidecar.
```text
[_version]
1
[_uuid]
f55dee18-3a90-47fe-aa29-4ecb1ce10424
[_type]
file-sidecar
[_description]
OAuth2 auth handler. Token lifecycle and refresh.
[_careful]
wuniq: target-uuid[SECRETS]: Never cache secret values
Redis connection required.
[DECISIONS: Architecture Decision Log]
Chose JWT over sessions for statelessness.
[DECISIONS/Auth]
PKCE is required for public clients.
```
## Repairing corruption
Native editing of `.wuniq` content is allowed only when KaKeKiKoKu can no longer read or edit
the file.
Preferred approach:
1. Read the raw file natively in read-only mode.
2. Create a valid resource with `new`.
3. Transfer knowledge through `edit`.
4. Edit in place only if recreating would lose the UUID or incoming references.
Check:
1. Valid private fields.
2. `_description` present.
3. Blank lines before headers.
4. Header-like content rewritten inside prose or inline code.
5. Valid relations.
6. Nothing before the first header.
7. No subsection under a private parent.
8. Clean `sync` afterwards.
## Resolving complete Git conflicts
Use native tools only on the exact `.wuniq` file reported by sync. Resolve every block,
preserve UUID, fields, relations, and non-conflicting knowledge. Ask the human when
intent is ambiguous. Do not stage or commit without an explicit request. Run `sync`
when finished.
Gotchas:
- Relation descriptions do not allow brackets.
- A malformed `wuniq:` line may appear as text and must be recreated with
`relation add`.
- Subsections cannot exist under a private parent.
- Text before the first header is invisible and will be lost when saving.
---
Base guide and complete topic index: `help`Generated verbatim from the help command of KaKeKiKoKu Studio · last regenerated July 30, 2026 · regenerated with every release.