8. The Web UI — Sync & Issues

KaKeKiKoKu uses two coordinated surfaces for sync. The bottom bar is always visible: it shows the overall status at a glance and hosts the actions you trigger most (Analyze, Analyze + AI, the automatic-open toggle and the sync sound). The right panel appears automatically only when there are pending issues to review; when everything is clean, it gets out of the way.

Right panel — Issue viewer

What synchronization is for

Synchronization is the mechanism that keeps your project's knowledge up to date. Its goal is to detect any place where your files and their context no longer agree, and resolve it — ideally automatically.

KaKeKiKoKu treats knowledge as the central axis of the project. That's why it's insistent: it takes care of automatically reminding your AI to synchronize after making changes. Sometimes it may seem pushy, but it's intentional — if knowledge falls behind, the whole system loses value.

How automatic synchronization works

KaKeKiKoKu monitors your project in real time. When it detects changes in files, it waits for a moment of silence and launches an automatic analysis. If it finds issues, it prepares a sync request for your AI: in Automatic mode it sends the request through an event; in Precise mode it alerts you so you can paste it when you decide.

Important about events: live delivery requires an MCP client with channel support. See the Claude Code guide for the recorded setup. The instruction-file HTTP connection returns commands and uses Precise mode; it does not receive these background messages.

If you use local HTTP or an MCP client without channels: KaKeKiKoKu works in Precise mode. Buttons and alerts do not disappear: they translate the action into text, copy it to the clipboard, and you paste it into the AI chat. Less automatic. More controlled.

When the panel appears

The right panel is automatically shown when at least one pending issue is detected, and hidden when everything is clean. While the bell toggle in the bottom bar is on, this is a strict rule: if you close the panel manually while issues remain, it will reopen on the next change KaKeKiKoKu detects. The bell is the only opt-out — turn it off to stop the panel from reopening on its own; the SYNC indicator in the bottom bar will still flash to alert you when new issues appear.

Focus mode keeps the right panel hidden while you work. When you leave focus mode with the bell on, Studio immediately checks the issues already detected and opens the panel if any remain, including relationship reviews requested through MCP or HTTP. It does not wait for another analysis. With the bell off, leaving focus mode restores the previous panel visibility.

The open resource also has its own notice in the central panel when out-of-date context or relationship reviews are detected. It remains available in focus mode and with the bell off.

The actions that used to live at the top of this panel (Analyze and Analyze + AI) are now part of the bottom bar — see Bottom bar — Status and actions below.

Issue list

After analysis, issues appear grouped by type and ordered by repair flow. Unresolved Git conflicts in KaKeKiKoKu contexts come first because they block trustworthy analysis for that project; then come broken references, relations to review, out-of-date context, resources without context, recent resources without context, ghost contexts, and finally unsupported formats, validation errors, structural warnings, and the automatic repairs already applied. Each issue shows the affected resource's path and the actions available for that case:

🔴 Git conflicts in KaKeKiKoKu contexts — red

If Git leaves a complete conflict block inside a .wuniq file, KaKeKiKoKu treats that context as untrusted and blocks synchronization for the affected project. It does not report secondary issues such as broken relations or resources without context until the conflict is resolved, because those results could be misleading. Other open projects continue to synchronize normally.

The conflicted context is temporarily absent from the navigation tree and search results. The issue appears at the top of this panel with the physical .wuniq path and counts toward the existing red Errors counter. It cannot be acknowledged, untracked, excluded, deleted, or repaired manually from the panel.

• 🤖 Fix with AI: asks your AI to inspect and repair that exact .wuniq file. KaKeKiKoKu tells it to preserve the UUID, private fields, sections, relations, and all non-conflicting knowledge; to ask you when the intended merge is ambiguous; and not to stage or commit anything unless you explicitly request it.

After the file is repaired, run Analyze again. The context returns to the tree and KaKeKiKoKu resumes the project's normal validation.

🔗 Broken references — orange

Relationships pointing to resources that can't be located. Broken references are shown separately from other errors for easier identification. Options:

• 🤖 Fix with AI: your AI analyzes the reference and repairs or removes it.

▲ Out-of-date context — amber

Files that changed but whose context hasn't been updated. Options:

• Acknowledge (ack): marks the out-of-date context as reviewed without making changes. Useful if the context is already correct despite the file change.
• Acknowledge all: acknowledges all out-of-date context at once.
• 🤖 Fix with AI: your AI reads the updated file and corrects the context.

⌛ Resources without context — amber

Inherited files without context. Shown in batches of up to 25.

When there are 25 or fewer: listed directly in the panel and your AI adds context to them as part of its normal syncs.

When there are more than 25 (a large project just opened, for example): an OFF / ON switch labeled Add context with AI appears above the list.

• OFF (default): your AI does not see these resources — it avoids adding context to hundreds or thousands of files without your consent.
• ON: KaKeKiKoKu signals your AI immediately and it starts adding context in batches of 25, requesting the next after each one. You can leave it active and walk away — the AI works on its own until the pile is empty or you click OFF.
• Clicking OFF while the AI is processing: it stops after completing the current batch (no mid-batch interruption).

Per-item options in the list:

• Untrack: marks the resource as untracked. KaKeKiKoKu will no longer require a context for it.
• Exclude: excludes the resource completely from the KaKeKiKoKu project. Shows a confirmation dialog to prevent accidental exclusions.
• 🤖 Fix with AI: asks the AI to add context for that specific item, which works transparently in either Automatic mode (sending the request through the live channel) or Precise mode (copying the request to the clipboard).

Per-batch options (when batch processing is active):

• 🤖 Fix with AI: your AI adds context to the batch. For each resource it decides before acting: if auto-generated or third-party (node_modules, bin/obj, .git) it excludes it with config add excluded; if junk or stale it marks it untracked or asks; if real source or documentation it adds context to it. When done, a new sync presents the next batch.

❓ Recent resources without context — blue

Files or folders created or modified during the current session that don't have context yet. Options:

• Untrack: marks the resource as untracked. KaKeKiKoKu will no longer require a context for it.
• Exclude: excludes the resource completely from the KaKeKiKoKu project. Shows a confirmation dialog to prevent accidental exclusions.
• 🤖 Fix with AI: your AI creates the context with an appropriate description automatically.

Images referenced via Markdown from any context (with the ![alt](path) syntax) are automatically excluded from this list. KaKeKiKoKu considers them justified by their reference and does not insist on adding context for them — see chapter 4 (Images and Markdown).

👻 Ghost contexts — purple

Contexts whose original file no longer exists. Options:

• Clean: deletes the ghost context.
• Clean all: deletes all ghosts at once.
• 🤖 Fix with AI: sends the case to your AI to decide (it may convert it to an entity, delete it, or investigate what happened).

🔴 Errors — red

Validation problems: empty required description, unfilled required fields, malformed configuration, duplicate UUIDs, and the Git-conflict group described above. These require direct correction.

• 🤖 Fix with AI: your AI attempts to resolve the error.

Relations to review

This group asks you to check whether a resource's knowledge is still valid after changes to connected knowledge. A review does not mean that the knowledge is wrong. It is a Warning, separate from broken links, out-of-date context, and the manual pending or draft flags. The resource count and the number of individual reviews are shown separately.

Use the chevron beside a resource to expand its reviews; its name opens that resource. Each detail first explains what needs checking and which connected knowledge changed. Two actions keep those roles clear:

• Open … for review is the primary action. It opens the resource or block whose knowledge you need to assess.
• Consult … opens the connected resource or block whose changes prompted the review. Use it to understand those changes and their possible effect on the knowledge you are reviewing.

Both actions select the destination in the left tree and open the corresponding block in the central panel. Their roles stay the same after navigation. The relationship's direction, declaration and reason appear below as supporting information.

Once the resource you are checking is open, you can also read the other end without leaving it: click a relationship chip in the central panel, or use the eye (or Alt+click) on the matching row in the tree, and the connected resource appears in the consult area under the editor, opened on the block involved, with the relationship and its reason named above it. Reading there is read only and accepts nothing.

For a relationship A → B, either end can need review:

The explanation also distinguishes the scope of the changed knowledge. A relationship to a resource description covers the whole resource; a relationship to a section covers that section and its subsections; a relationship to a subsection covers its own text. For a whole resource or section, the message identifies the affected scope without claiming that its description or top-level text was the exact part edited.

To keep reviews focused, link to the relevant section or subsection at each end. Reserve a whole-resource relationship for a dependency that really concerns all of its knowledge; its wider scope can prompt reviews when other parts of the resource change.

Reading or opening accepts nothing. After assessing the knowledge and updating it if needed, use Give conformity for that review. The action for all current reviews of the resource appears at the end and includes reviews beyond the displayed list. The result shows how many were accepted and how many remain. Accepting one end does not accept the other; reciprocal relationships are independent. Requesting review for a further edit may legitimately create another review, even on the same relationship. See the save choices. A broken link must first be repaired or removed.

Saving or giving conformity updates the current reviews without requiring another analysis. Changes made outside Studio appear on analysis without writing tracking metadata back to files. If an owner cannot be saved, successful acceptances remain applied and the remaining failures are reported. Pause and the existing analysis notification controls keep their normal behavior.

Update Studio for a newer format

If a context uses a newer Wuniq format or knowledge hash recipe, update KaKeKiKoKu Studio before opening or changing it. This is not a missing description or a corruption repair task. Studio preserves the file and does not offer an editor or an AI repair action for it; other supported resources remain usable.

⚠️ Other issues — structural warnings

Minor format or configuration problems that don't corrupt anything but shouldn't be left lying around: subsections without a section, name collisions, text sitting outside the format, or a context left behind for a resource you excluded. They have their own counter so they never get confused with real errors.

• 🤖 Fix with AI: your AI tidies up the affected resource.

🔄 Automatic repairs

Not a problem — a receipt. This group lists the safe fixes the last analysis applied on its own (a renamed folder whose context followed it, a moved file matched by content). No action is needed; it's there so nothing KaKeKiKoKu changes happens behind your back.

Responsive design

If the right panel is narrow (e.g., when reduced with the splitter), text labels hide and counters stack as icon + number. Everything remains functional, just more compact.

Bottom bar — Status and actions

The bottom bar is divided into three zones:

Left zone — Sync status and actions

• Pause/resume button: pauses and resumes automatic change monitoring. Useful if you're about to make many changes in a row and don't want KaKeKiKoKu launching intermediate syncs.
• Timer status: shows the current state of automatic synchronization:
  • "Waiting for changes...": KaKeKiKoKu is monitoring but there are no pending changes.
  • Countdown (M:SS): the analysis already ran and found issues; what the clock counts is the minute before KaKeKiKoKu signals that issues need attention. It restarts whenever a new analysis returns a different picture, so a burst of edits produces one notification, not ten — and if you fix everything in the meantime, it cancels itself and nobody gets bothered.
• 🔍 Analyze: runs a manual synchronization. Scans the entire project and detects issues. It is a refresh for you: it updates the panel and the counters and never pressures your AI, even if it finds problems.
• 🤖 Analyze + AI: analyzes and hands the current issues straight to your AI, with no waiting. This is the explicit "deal with it now" path. The button only appears in Automatic mode with the AI connected — it is the one action that needs a live channel. In Precise mode you get the same result by asking your AI for a sync in the chat.
• 🔔 Bell toggle: controls whether the right panel opens automatically when new issues appear. On by default. When off, the panel only opens manually; the SYNC indicator still flashes when issues appear so you don't miss them.
• 🔊 Sync sound toggle: turns the sync notification sounds on or off (beep when something goes wrong, pleasant sound when everything is clean, descending tone when the sync timer expires). Independent from the bell — one controls visibility, the other controls audio.

The panel and the AI receive different views on purpose. The human issue panel keeps the complete typed result, with no 30,000-character text restriction. Text delivered to an AI — through HTTP, MCP, or Analyze + AI — has a 30,000-character safety budget. In the exceptional case where the current issues do not fit, KaKeKiKoKu includes only complete issues and ends with ... and X more issue(s). Nothing is cut in half. Let the AI resolve the issues shown and run sync again; KaKeKiKoKu recalculates the state and returns whatever still remains.

This safety cut does not replace the policy for resources without context above. Projects opened without existing KaKeKiKoKu context still expose at most the configured batch (normally 25) when processing is enabled, while a large backlog remains invisible to the AI when the switch is OFF.

KaKeKiKoKu watches for file changes and uses fallback polling when file-system notifications miss them. Automatic analyses update the panel and respect the minimum interval configured in Settings. A separate one-minute countdown handles the notification: changed issue results restart it, and resolved issues remove the need to notify. Background delivery requires Automatic mode, an MCP connection, and a client that delivers channels. HTTP provides command responses without background channel messages. In Precise mode, consult the panel and ask your AI to run sync.

Center zone — Counters and navigation

Eight counters show the current categories, with the same icons and colors as the right panel. Relations to review count affected resources, with the number of individual reviews shown separately. A counter only appears when it has something to count — when everything is resolved you see “All clean — no issues found” instead.

Issue navigation: clicking on any counter activates navigation for that issue type. ◀ ▶ buttons and an X/N indicator show which one you're on. When navigating, the central panel jumps automatically to the affected resource — so you can go through all issues of a type one by one, reviewing or fixing them without manually searching the tree.

AI activity: next to the counters, a small glowing capsule lights up each time your AI runs a KaKeKiKoKu command, showing the operation and the resource it touched (the full path is in the tooltip). It uses the same colors as the K logo in the top bar — read, write, sync — and it queues rather than overwrites, so a burst of commands scrolls past one at a time instead of blurring into one flash. It's the quiet answer to "what is my AI doing right now?".

Right zone — AI connection

The Automatic / Precise sync mode is configured in Settings > Application. See chapter 10 for what each mode does.

AI connection: the indicator reflects recent communication, not a guarantee that the client can receive background messages. An HTTP session has no background heartbeat; verify it with a real command such as open list.

• 🟢 Connected: your AI is active and communicating with KaKeKiKoKu.
• 🔴 Disconnected: no connection. The "Fix with AI" buttons will still be visible but KaKeKiKoKu will alert you if you try to use them.