This page is written for AIs. Humans are welcome.
Below is the exact text an AI receives from KaKeKiKoKu’s introductory help command and every help <topic> command listed in its index — the complete operating guide: workflow, commands, format specification, and rules. The public help is reproduced verbatim; the development-only preamble is excluded.
It is published for two reasons. Transparency: you can inspect the published help corpus. Tool descriptions, command responses, and your own project context also guide the AI. 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: use this guide together with the help from your installed version and the context of the project you are working on. Start every session with open list.
help# `help` — Introductory guide and index
KaKeKiKoKu Studio (Knowledge Engine) is a project knowledge system. It keeps decisions,
constraints, intent, risks, rejected alternatives and relations alongside real files. It
complements inspection of those files and human documentation; it replaces neither.
A “sidecar” or “context” is a `.wuniq` knowledge file. `read` retrieves that context,
not the real file. Use native tools for real files; use the command interface for context. Native context
repair and moving sidecars have narrow exceptions in `help format` and `help context`.
## 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"
```
To initialize a project requested by the human, its folder must already exist.
`open` creates context and configuration, not the folder or real files:
```text
open "C:/myproject"
--description "Structured knowledge 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.
Blocks may have a human-readable title. Limits: 40 characters per name segment;
30 top-level sections (including `_description`) and 60 subsections per resource;
4,000 characters per block and 52,000 characters of prose per resource.
Relations connect complete blocks and survive moves through stable identity. Manage them
with `relation`; never write raw `wuniq:` lines manually.
Knowledge edits require a quoted `--impact "yes"` or `--impact "no"`, even when no
relations are visible. Context creation requires either `--no-relations` or explicit
`--relation` clauses; choose pertinent connections, without inventing them. A review
notice supplies the exact `relation pending` command; its results supply reads and acks.
## Essential syntax
The canonical form is:
```text
<command> [<action>] ["<target>"] [--option "<value>"] [--flag]
```
Quote paths, section names and other values. Relative resource paths start at the selected
project root, never at the last folder read. Do not use `key=value`, `+=`, `-=`, `Project::path`,
or section names as keys. Complete rules:
```text
help syntax
```
## Progressive reading
Every AI command 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"
```
An oversized folder read omits the listing and provides a `contents` command.
`max_folder_items` also caps listings. Omissions are declared; use native file tools
to select omitted paths, then read their context. A fragment is never presented as complete.
## Writing knowledge
Record decisions, constraints, rationale, conclusions, rejected alternatives, non-obvious
gotchas, and human intent as they are reached. Do not archive routine edits or facts that
are obvious from the code. Exploration is not knowledge until the human settles it: if the
human asks not to record, write nothing until asked; if unsure, ask. Project knowledge
lives here: do not keep its decisions in client memory or skills.
Write rules as a standard plus its reason, not as bare prohibitions: the reason lets others
apply the rule to cases its author did not foresee.
Contexts describe present truth, not a changelog. Rewrite an obsolete note instead of
stacking dated corrections. If a problem remains unresolved, record the diagnosis,
attempts, and rejected approaches before finishing, and explicitly tell the human.
Organize distinct topics in named subsections such as `_careful/Compatibility` and
`DECISIONS/Auth`. Extend an existing block only for the same topic. Markdown headings
inside prose do not create subsections; do not wait for a size limit to structure knowledge.
Run `sync` after each batch; do not depend on notifications. Inspect changes before
updating context or accepting drift. Complete doctrine: `help workflow`.
## Multi-project scope
With one project open, `--project` may be omitted. Otherwise, select its root folder name,
not its path. Keep projects open and switch scope with this option:
```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
```
Targets of a single-project command must all belong to that project.
## Essential commands
```text
open list
current
read "path"
read "path"
--section "_description"
contents "folder/"
search text "query"
new "path"
--description "What it is and what it does."
--no-relations
edit set "path"
--section "_careful/Compatibility"
--content "Durable compatibility constraint."
--impact "yes"
relation add "source"
--section "_careful/Compatibility"
--target "target"
--description "Reason for the dependency."
sync
```
## Web and product questions
The local Web, MCP and HTTP bridge share project state and the same 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://www.kakekikoku.com/
- https://www.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 current Identify the Web view and file associated with this AI connection.
help close Close a project for every connection.
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, inspect, review, and acknowledge 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.
Except for escaping a quote, backslashes are literal: `C:\temp`, `C:\node_modules`,
`\\server\share` and written `\n` survive unchanged. This is command syntax; if the transport
serializes it as JSON, JSON escaping still applies at that outer layer.
Write multi-line content with a real line break inside the quotes:
```text
edit set "notes.entity"
--section "STEPS"
--content "First line.
Second line."
--impact "yes"
```
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 `/`.
- Prose accepts LF, CRLF (normalized to LF), and tabs. Other control characters,
including a lone CR, are rejected. Use real line breaks for multiline values.
## 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"
--impact "yes"
```
`_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"
--impact "yes"
```
Aggregators accept one of these options:
```text
--project "MyProject"
--all-projects
```
Only `search text`, `search structured`, `stats` and `sync` accept `--all-projects`.
It cannot be combined with `--project`; `sync ack` always targets one project.
## Errors
A syntax error identifies the missing, unknown or incompatible operand and gives the
canonical usage. Correct that command; an invalid option is never silently reinterpreted
as a section or another operation.
---
Base guide and complete topic index: `help`help kakekikoku# `help kakekikoku` — Product and local Web
KaKeKiKoKu Studio is a project knowledge system shared by humans and AIs. A project is its
knowledge: the human shapes it, alone or with any AI, and Studio keeps it structured beside
the files. It records what normally disappears between sessions: decisions, constraints,
intent, rationale, rejected alternatives, risks, relations, and non-obvious operational
context. Persistent memory is one capability, not the product's purpose.
KaKeKiKoKu is not a static context file. Knowledge is divided into blocks with identity,
indexed, related, read progressively, edited through the Web or an AI connection, 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. The AI client still processes the context you give it.
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 context. Excluded leaves KaKeKiKoKu's scope. KaKeKiKoKu rejects both transitions while
context still exists, so knowledge is never deleted silently.
## Human and AI
Web, MCP and HTTP share project state. 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.
- Add context, 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://www.kakekikoku.com/
- https://www.kakekikoku.com/docs
- https://www.kakekikoku.com/docs/integrations/
- https://www.kakekikoku.com/docs/troubleshooting
- https://www.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
Record decisions, constraints, rationale, rejected alternatives, non-obvious gotchas
and human intent. Omit routine changes and obvious facts unless they reveal a stable
rule or trade-off. Describe current reality and its reasons, not a changelog: rewrite
obsolete notes. Date decisions or incidents, not every edit.
Useful signals:
```text
"We chose X because..." _conclusions 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,
record 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 the batch. Resolve issues within the agreed scope and report any
that remain; never acknowledge drift without checking the actual changes.
## 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
Use named subsections for distinct topics, e.g. `DECISIONS/Auth` and `_careful/Concurrency`.
Before writing, inspect existing blocks: update the matching topic or create a named child
for a different one. Extend a block only with knowledge about that same topic. A short,
single-topic section can stand alone; do not manufacture a subsection for every paragraph.
Markdown headings inside prose do not create blocks. Structure by meaning from the start,
not only when a size limit forces a split. Use entities for cross-cutting knowledge and
relations for dependencies. Never cut knowledge merely to satisfy a limit.
---
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 folder must exist and differ from the configured AI working directory (the project
container). If that directory is unset, ask the human to configure it. Relative open
paths use that directory; prefer absolute paths. Initialization creates only
`.wuniq/config.yaml` and root context if missing, and reads the root.
A successful `open` links this AI connection to the project for `current` routing.
`open list` only discovers projects; it creates no links. Open only projects needed for
the task or explicitly requested by the human. Closing a project clears every AI link
to it; reopening it from the Web does not restore those links.
Reopening refreshes disk state and resets the shared read registrations for that project.
Read affected resources again before editing. To switch projects, use `--project`
instead of reopening.
If the response exceeds 30,000 characters, the project stays open but the root read is
omitted, with an exact recovery command. Read the root later 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`
Lists projects available to AI, including closed catalog entries, with root descriptions
to help choose the relevant ones. At most 30 are shown: open projects first, then closed
entries in catalog order. If more exist, the response reports omissions and points 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"
```
Example initialization:
```text
open "C:/myproject"
--description "Structured project knowledge."
--recursive
```
---
Base guide and complete topic index: `help`help current# `help current` — Current Web view
```text
current
```
No arguments or `--project`. With MCP, operational commands start the local Knowledge
Engine if needed; MCP initialization and `help` do not start it. With the HTTP agent
bridge, the human starts Studio first, including for help and initialization.
Starting the engine does not mean a browser has connected: `no_ui` or `loading` is normal.
## Scope and selection
Each AI connection is linked only to projects it successfully opened with `open`.
Several connections can link to the same project. `open list` creates no links. Closing
a project ends all its links; human reopening does not restore them. Reusing a live
connection identity preserves links. HTTP sessions expire on restart or inactivity;
initialize again and open needed projects. Links route views, not exclusive ownership.
Among connected Web tabs showing a linked project in the central panel, selects the
one most recently used. The result labels its selection and whether another tab was
used more recently. This is a recorded interaction, not a claim about OS foreground focus.
With one matching tab and no recorded interaction, selects it explicitly; with several
unranked matches, returns `ambiguous` rather than guessing. Disconnected tabs are ignored.
When there is no matching project view, a known last-used global view (Welcome or app
settings) can be reported. Otherwise a nonmatching project's identity is not returned.
## Response
`status`, `caller_projects` and optional `view`, `project`, `project_path`, `path`,
`resource`, `selection`, `other_tab_used_more_recently`, `last_used_at_utc` and
`rendered_at_utc`. Paths are absolute; `resource` is the logical command target for a later
`read`, with `--project` when needed. Text values use JSON quoting.
For `view: context`, `path` is the physical `.wuniq` file for a file, folder or entity.
For `view: source`, it is the actual source/document file in the central panel.
Other views include `welcome`, `application_settings`, `project_settings`, `schema`,
`creation`, `project_map`, `excluded`, `untracked` and `no_context`; these do not imply
an open document. Missing context/source becomes `context_unavailable`/`resource_unavailable`.
States without a selected view:
- `no_ui`: no Web connection; the engine may just have started.
- `loading`: the connected view has not reported its panel yet.
- `no_projects`: this AI connection has no project links.
- `no_matching_view`: connected project views do not match this connection's links.
- `project_unavailable`: a displayed project was closed or is no longer visible to AI.
- `ambiguous`: several matching views exist without interaction ordering.
- `caller_unavailable`: no usable AI connection identity was supplied.
This command returns metadata only. It neither navigates nor opens projects, reads
document bodies, or registers context as read. Use `read` before working on code or context.
---
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 shared session and releases its graph and read registry. The
Web and every AI connection share that session: closing a project closes it for all of
them and ends their links. Do not close a project just to finish your work or disconnect.
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
Read-state is tracked per resource. Knowing its structure permits partial reads;
`read` without selectors or a selection that delivers `_description` also enables mutation:
| Command | Partial reads | `edit`, `move`, `relation` |
|---|---|---|
| `read "path"` (including automatic compact output) | yes | yes |
| `read "path" --section "_description"` | yes | yes |
| `read "path" --section "_description" --section "A"` (content delivered) | yes | yes |
| `read "path" --index` | yes | no |
The first read of each resource is complete by default. A selection containing `_description`
is always allowed, alone or with other blocks; `new` registers the created resource as read.
After `--index`, selected-block reads do not by themselves enable editing: also read
`_description` or use an unqualified `read`. Regardless of that gate, inspect the existing
block before replacing it; automatic compact output has not shown its content.
If an oversized combined selection returns only its index, it does not enable editing:
read `_description` alone or request a smaller group that includes it.
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
An oversized resource becomes its complete `_description` and canonical index, with
`context_parent` and bounded `referenced_by` guidance. Smaller resources remain complete.
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|contains> "<value>" ["<value>" ...]
[--match "<section>" <equals|contains> "<value>" ["<value>" ...] ...]
[--project "<project>" | --all-projects]
```
## Full-text search
Searches resource names, section/subsection identifiers and titles, `_description`,
reserved and custom section content, outgoing relation descriptions, paths, and real
file content. A relation match belongs to its source block; it is not duplicated at
the target through incoming references.
Exact-match weights (partial matches score less):
```text
name 15
_description 12
section identifier 5/4 (reserved/custom)
reserved 5
custom 4
path 4
relation description 4/2 (exact/partial)
real content 4 (cumulative maximum 14 per resource)
```
The query is split on spaces and every token must appear (AND). Operators such as OR,
NOT or regular expressions are not supported. Matching is
case- and diacritic-insensitive, so `"autenticacion"` finds `"autenticación"`. It uses
substrings, not whole words: `"cat"` may match `"application"`. 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.
Quote words to search an exact phrase. Inside the query, quotes are written as `\"`:
```text
search text "\"token refresh\" auth"
```
This finds resources containing the phrase `token refresh` as written, in that order,
and also `auth`. A phrase is a single term: it ignores case and diacritics, and runs of
spaces in the query count as one space, but its words must be adjacent on the same line,
in a file or in a context block (a line break splits a phrase). Phrases and words combine
with AND.
An unclosed quote takes the rest of the query as the phrase. To list every line or block
where a literal text appears inside one resource, use `search locate`.
At least one token needs 2 or more characters: a one-letter query is rejected because
it matches almost every resource. Minified files (`*.min.*`) are not searched by content;
they can still be found by name or path.
When a resource has several occurrences, they are the lines or blocks that contain every
token, or, if none does, those that contain any of them. The first occurrence is the best
hit and is the one the result shows.
## 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, including outgoing relation descriptions. File results
are one hit per matching line; context results are one hit per matching section or
subsection, not per textual occurrence. All search modes respect project exclusions
and the built-in traversal exclusions, including explicit locate paths and descendants
of excluded folders. Untracked files remain searchable.
## 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.
AI command interface (MCP and HTTP):
- 25 full-text candidates per project.
- 100 structured candidates per project.
- 50 locate hits (matching file lines or context blocks).
- 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.
The Web allows 500 global results, initially renders 100, then adds local chunks; it
does not use the AI command text budget.
With multiple projects, `search text` and `search structured` require `--project` or
`--all-projects`. `--project` searches only that project. `--all-projects` returns one
block per project, headed `── Name (root path) ──`; the limits above apply to each
project. Result paths are relative to their project, so to read or edit a result, repeat
the command with `--project "Name"` using the name in that header.
---
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>"]
--no-relations
new "<resource>"
--description "<description>"
[--set "<section>" "<content>" ...]
[--create "<section>" ...]
--relation "<source-block>" "<target-resource>" "<target-block>" "<reason>"
[--relation "<source-block>" "<target-resource>" "<target-block>" "<reason>" ...]
[--project "<project>"]
```
Examples:
```text
new "src/auth/AuthService.cs"
--description "Manages OAuth2 and the token lifecycle."
--no-relations
new "src/auth/"
--description "Authentication and authorization module."
--no-relations
new "decisions.entity"
--description "API architecture decisions."
--no-relations
new "planning.entity"
--description "Planning structure shared with the human."
--create "QUESTIONS"
--create "DECISIONS"
--set "STATUS" "In design"
--no-relations
```
## What it creates
Choose exactly one creation form. `--no-relations` means no pertinent connection is
identified now; it is not stored and does not prevent adding one later. Alternatively,
repeat `--relation` with four quoted operands. Both blocks must exist in the initial
models; `"_description"` addresses the whole resource. The reason may be empty, but a
useful reason guides review. All relations and content are validated before one write.
New relations accept both final contents. Adding blocks with `edit` does not repeat this
creation declaration; the Web retains its visual creation flow.
```text
new "design.entity"
--description "Design decisions that depend on current API knowledge."
--set "DECISIONS" "Use the API contract as the source of truth."
--relation "DECISIONS" "architecture.entity" "_description" "Keep design aligned with architecture."
```
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 base file
and may live in an existing subfolder, e.g. `docs/decisions.entity`.
## Initial sections
`--description` creates `_description` and is required, with 10–280 characters.
`--set` creates a block with content. Use named subsections for distinct topics;
Markdown headings within the text are not structural blocks:
```text
new "architecture.entity"
--description "Current product architecture."
--set "_careful/Compatibility" "Do not break format compatibility."
--set "DECISIONS/Auth" "Use short-lived tokens to limit exposure."
--no-relations
```
`--create` creates an empty section or subsection:
```text
new "planning.entity"
--description "Template for the human to complete."
--create "QUESTIONS"
--create "QUESTIONS/Compatibility"
--no-relations
```
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`.
Description-only creation prompts further context for folders, entities and files
created during the session. Pre-existing files instead follow the bulk-documentation
policy in `help sync`. With other initial sections, that NOTE is not shown.
## 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`.
- Missing creation choice: add either `--no-relations` or complete `--relation` clauses.
---
Base guide and complete topic index: `help`help edit# `help edit` — Edit blocks
`edit` modifies content, structure and metadata. First read the resource, at least its
`_description`; an index alone does not enable editing. All forms below accept
`--project "<project>"` (required with multiple projects open).
## Knowledge impact
Content and structure operations require `--impact "yes"` or `--impact "no"`, even
without visible links. Use one choice for the whole batch. The examples below use yes;
choose no when the change does not require neighbors to review their knowledge.
Yes preserves their accepted references and immediately reports current reviews with
exact consultation commands, even when their count stays the same. No advances only
references that were already conforming; earlier pending reviews remain pending.
An effective knowledge edit accepts current neighbors for the edited block and its
containing section/resource, not untouched children or siblings. No-op and title-only
changes accept nothing. Titles need no choice; a supplied choice is ignored with a note.
The Web asks once when its prepared change affects applicable connections.
If the principal was applied but additional owners failed, the response reports the
partial result. Inspect the saved state and remaining failures before retrying; do not
repeat an append that already succeeded. There is no global rollback guarantee.
## Content
### Set
```text
edit set "<resource>"
--section "<section>"
--content "<content>"
--impact "yes"
```
Creates the block if it does not exist and replaces all its content if it does:
```text
edit set "architecture.entity"
--section "DECISIONS/Auth"
--content "We chose JWT because it is stateless."
--impact "yes"
```
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>"
--impact "yes"
```
Adds a line to the same block. If the block does not exist, it creates it:
```text
edit append "architecture.entity"
--section "DECISIONS/Auth"
--content "Rotate refresh tokens to limit replay."
--impact "yes"
```
Append only to the same topic. For a different topic, create a named subsection with
`edit set --section "SECTION/Topic" --content ...` (and the resource).
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>"
--impact "yes"
```
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>"
--impact "yes"
```
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"
--impact "yes"
```
`--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>"
--impact "yes"
```
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>"
--impact "yes"
```
Empties prose while preserving the block, title, position and incoming/outgoing relations.
Not allowed on `_description`.
## Structure
### Create an empty block
```text
edit create "<resource>"
--section "<section>"
[--title "<title>"]
--impact "yes"
```
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"
--impact "yes"
```
It also creates named subsections:
```text
edit create "planning.entity"
--section "QUESTIONS/Integrations"
--title "Integrations to review"
--impact "yes"
```
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>"
--impact "yes"
```
This is the only `edit` operation that removes structure. Deleting a section also
deletes its subsections. It 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>"
--impact "yes"
```
Examples:
```text
edit rename "architecture.entity"
--section "Ideas"
--new-name "DECISIONS"
--impact "yes"
edit rename "architecture.entity"
--section "DECISIONS/Auth"
--new-name "DECISIONS/Authentication"
--impact "yes"
```
The rename is local to the resource, preserves content, title, and identity,
and updates exact incoming relations. 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>"]
--impact "yes"
```
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."
--impact "yes"
```
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]
[--impact "yes|no"]
```
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`, no impact choice is required and 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; include `--impact "yes"` or `--impact "no"` when confirming. 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>"
edit clear-title "<resource>"
--section "<section>"
```
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>...
--impact "yes"
```
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."
--impact "yes"
```
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. An exact existing `wuniq:` prefix copied from a read may be absorbed
unchanged; new addresses or changed reasons must use relation operations, never raw lines.
## Rules
- 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.
- Prose accepts LF, CRLF (normalized to LF) and tabs. Backslashes are literal except
before a double quote; other control characters are rejected (`help syntax`).
- 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.
- Coordinate edits to the same resource across clients and the Web. Shared state does
not provide transaction isolation; concurrent writes can conflict or lose updates.
Language keywords such as `section`, `title`, `target` and `rename` are valid quoted
section names; their role comes from the option, not the word.
---
Base guide and complete topic index: `help`help relation# `help relation` — Manage relations
Add/remove/description mutations require a prior source read; list, pending and ack
introduce no additional read requirement. All forms accept
`--project "<project>"` (required with multiple projects open).
## Syntax
```text
relation list "<source>"
relation add "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
[--description "<description>"]
relation remove "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
relation set-description "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
--description "<description>"
relation clear-description "<source>"
--section "<source-section>"
--target "<target-resource>"
[--target-section "<target-section>"]
relation pending "<reviewer>"
relation ack "<reviewer>"
--section "<reviewer-block>"
--related "<other-resource>"
--related-section "<other-block>"
--direction "incoming|outgoing"
relation ack "<reviewer>"
--all
```
## Behavior
Relations connect blocks and form a knowledge graph. On disk, targets are stored as UUIDs
so relations survive moves and renames.
Use project-relative logical paths in `--target`. Adding a relation also accepts an
existing UUID from that project; invented or cross-project identities 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>]`.
`list` shows every address in full. `read` bounds the locator of each relation it shows
to 260 characters (cut at the start and marked with `…`), so use `relation list` when the
complete address matters.
`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 the description. To remove a
broken target, pass the exact UUID from `[BROKEN_REFERENCE: <uuid>]` as `--target`,
without the wrapper, and preserve any `--target-section`. The target need not still exist.
`set-description` changes only the description. Changing the target or target section
requires remove + add.
`clear-description` preserves the relation and removes its description.
Changing only a reason preserves both review references. A new connection accepts both
current contents; changing its destination requires removing it and adding a new one.
## Pending reviews and conformity
A -> B is owned by A. If B's addressed knowledge changes, A has an outgoing review;
if A's source knowledge changes, B has an incoming review. Reciprocal declarations are
independent. Titles, reasons, flags and technical fields do not change knowledge.
`_description` addresses the entire resource; a section includes its children and a
subsection addresses its own prose. Broken connections must be repaired or removed.
`pending` returns up to 25 complete current entries in deterministic order, across all
blocks and both directions. Each identifies reviewer, other end, reason and exact read
and ack commands. It reports the remaining count; resolve the displayed entries and
repeat the same command. Reading, listing or repeating does not accept reviews.
Individual ack accepts only the chosen reviewer's end against the other end's current
knowledge at execution. Incoming means other -> reviewer; outgoing means reviewer ->
other. Both selectors are explicit, including `"_description"` for whole resources.
Use one direction value, `"incoming"` or `"outgoing"`, never the combined syntax label.
`--all` excludes individual selectors and accepts all current resolvable pending ends of
that resource, including entries beyond the displayed 25 and hidden blocks. It does not
ack broken connections. Results give actual accepted and remaining counts plus any
owner failures; successful owners remain applied. Already conforming ends accept zero.
Ack needs no extra confirmation, read-version guard or impact choice and does not itself
propagate a knowledge change. Accept only after assessing the related knowledge.
```text
relation pending "design.entity"
relation ack "design.entity"
--section "DECISIONS"
--related "architecture.entity"
--related-section "_description"
--direction "outgoing"
relation ack "design.entity" --all
```
## Identity
Identity is the source block, target resource and optional target section/subsection.
One source block cannot repeat an address; different target sections are distinct.
## Rules
- Adding a relation requires target context and a UUID.
- The source section must exist, even if it is empty.
- When adding, an addressed target section/subsection must exist.
- 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
## Relation reviews
Sync reports a Warning per resource that has pending relation reviews, with the number
of reviews separately. This calculated state is distinct from the manual pending/draft
flags and does not replace broken-link or structural errors. Use the supplied
`relation pending` command to inspect both ends and exact read/ack actions. A second
stable sync writes nothing; external edits or Git changes show current discrepancies
without materializing tracking. A known provisional reference is persisted only on the
next effective owner save. Returning to the accepted knowledge removes the discrepancy.
## 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 contexts.
- 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 knowledge 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 add context to that batch on its own
initiative; `stats` always shows real coverage.
## AI command 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
`sync ack` acknowledges the real-file/context drift fingerprint. It does not accept
relation reviews; those use `relation ack` with their reviewer and chosen end.
When the context remains accurate:
```text
sync ack "src/auth.py" "src/helpers.py"
```
When the change introduces decisions, rules, intent, or gotchas, record 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:
- Untrack 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"
```
Example: `config set "language" "en"`.
Both limits accept positive integers. `max_folder_items` caps folder listings, `graph`
and `view`; it is not the search result limit. These are project settings, not the
application's analysis interval or AI mode.
## `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.
- Must not have 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
Each quoted operand is one pattern; commas inside it are literal. Matching is
case-insensitive. Use the forms below, not general shell globs: `?` is literal and
`**/name/**` is a special recursive form, not support for arbitrary globstars.
```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"
--impact "yes"
edit delete "architecture.entity"
--section "Obsolete"
--impact "yes"
```
---
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.
## AI command 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. For real files and folders, follow the native-move procedure below.
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.
If the pairing is ambiguous, read the ghost and identify its real resource first.
Move the sidecar with that resource and run `sync` to preserve its UUID and knowledge.
For folders, keep the folder-sidecar naming convention. Use `clean` only for genuinely
obsolete context, after rescuing any unique knowledge; it is not a rename.
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` does not register individual reads. Before editing a result, read its context:
```text
read "resource"
```
If this returns compact output, retrieve the block with `--section "SELECTOR"`
before replacing it. A first partial read alone is not permitted (`help read`).
## AI command 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
Restoring actual knowledge or changed connections resets acceptance selectively against
the resulting contents, including resolvable owners outside the snapshot. Unchanged
knowledge and unrelated pending reviews keep their prior acceptance; technical tracking
differences alone do not select a reset. Archived snapshots are never rewritten. If
physical restore applied but owner maintenance failed, inspect the explicit partial
result before retrying; there is no global rollback promise for that maintenance.
## 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.
Snapshots include real project files, not only context. Restoring can overwrite code
and remove conflicting context identities: inspect the preflight before confirming.
## List
Lists snapshots newest first: ID, UTC time, origin, copied/skipped file counts and label.
The AI command 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. 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.
A damaged current `.wuniq` may be replaced by its sound snapshot copy; a damaged snapshot
copy is rejected. A context with a newer format or hash recipe is never overwritten.
Current contexts whose identity cannot be read are listed as not inspected and left
untouched; they do not block the restore.
It checks the restore before writing and attempts rollback on failure; inspect any
reported recovery errors. After success it 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 is 1.1, independently of the product version and transport protocol.
`[_format]` governs structure; no marker means legacy 1.0. `[_version]` stamps the product
that wrote the file, not format compatibility. Effective saves adopt 1.1; open, reads,
listings and stable sync do not convert files. This reference helps understand, rescue,
or repair context; it does not authorize ordinary native editing.
A newer format or knowledge hash recipe requires updating KaKeKiKoKu Studio before
opening or changing that context. Its bytes are preserved and other supported contexts
remain usable. Older Studio 1.18 and earlier do not understand tracked 1.1 relations;
upgrade Studio to use them. The new protection is not retroactive.
## 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
[_format]
[_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. Command syntax explicitly creates or preserves
them:
```text
edit create "path"
--section "QUESTIONS"
--impact "yes"
edit clear "path"
--section "QUESTIONS"
--impact "yes"
```
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/Compatibility"
--target "target-resource"
--target-section "Section/Sub"
--description "Reason"
```
Do not write `wuniq:` lines with `edit`.
### Internal review references
Physical 1.1 relations may have a separate technical segment before the reason:
```text
wuniq: target-uuid[Section] {source_hash=sha256:v1:<64-hex>;target_hash=sha256:v1:<64-hex>}: Reason
```
Source and target references record accepted knowledge for the two reviewing ends.
They are not history or manual flags. The segment is system-managed, omitted from AI
knowledge renderings and Markdown exports, and does not consume the prose/reason lane.
Do not add tracking through commands or copy it into authored content.
Absent references remain absent in the parsed model. The first known current reference
may live provisionally in project memory; valid persisted references take precedence.
Rebuilding the index or rereading keeps known provisional values. Closing before an
effective owner save loses provisional memory; there is no forced write on close.
Full development recovery retains it; fallback explicitly cannot promise that.
Deleting a persisted reference resets only that end and may accept current content.
Present invalid or duplicated values block normal writes and are never covered by RAM.
The sha256:v1 recipe follows authored prose and complete addressed structure: whole
resource for _description, section plus children, or a leaf. Titles, reasons, paths,
UUIDs, flags and private fields do not change knowledge. Meaningful case and spaces
remain significant; storage line endings and parser-eliminated blanks do not.
## 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.
The separate bounded physical allowance covers tracking metadata without reducing
authorship capacity; the AI response limit remains 30,000 characters.
## Format rules
- Blocks are separated by a blank line.
- UTF-8; BOM is managed.
- All content uses the configured language.
- Prose may use Markdown; its headings do not create Wuniq format sections.
- A content line cannot look exactly like a Wuniq format header, even inside a code fence
or 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
This conceptual example separates the format from the current product version.
```text
[_format]
1.1
[_version]
1.21.0
[_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 recoverable content with `read`; keep the original file and all its knowledge.
A newer format/recipe is not corruption: update Studio rather than rewriting it.
2. For this exact damaged file only, inspect and repair the original with native tools.
3. Preserve UUID, private fields, sections and relations. Never invent an identity or
choose between conflicting declarations; ask the human when intent is ambiguous.
4. Create a replacement resource only with explicit human agreement.
5. Run `sync` after repair. Normal writes remain blocked while the container is unsafe.
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.
If the conflict concerns an accepted relation hash, keep either valid branch value;
never erase it to resolve the conflict. If it equals the merged knowledge, that branch
already reviewed it; otherwise the difference remains pending. Removing it would
initialize from current content and silently accept it. Preserve each end independently.
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 not ordinary block content; rescue it before repair.
Normal writes reject an unsafe container instead of silently discarding it.
---
Base guide and complete topic index: `help`Generated verbatim from KaKeKiKoKu Studio 1.21.0 · captured and verified 2026-10-22 · 22 responses in canonical index order. Consult the help from your installation if its version differs.