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 desynchronization between your files and their documentation, and resolve it — ideally automatically.

KaKeKiKoKu treats documentation 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 documentation 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: Real-time event reception is still a recent capability. Today, only Claude Code supports channels, so it is the only client where KaKeKiKoKu can push events directly to the AI. This is not a KaKeKiKoKu limitation; it is the current state of AI clients.

If you use Codex, Antigravity, Claude Desktop, or another 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.

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, drift, pending documentation, recent undocumented resources, ghost sidecars, and finally validation errors, structural warnings, and the automatic repairs already applied. Each issue shows the affected resource's path and, next to it, action buttons:

🔴 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 missing sidecars 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, dismissed, 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.

▲ Drift — amber

Files that changed but their sidecar hasn't been updated. Options:

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

⌛ Pending documentation — amber

Inherited files without a sidecar. Shown in batches of up to 25.

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

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

• OFF (default): your AI does not see these resources — it avoids documenting hundreds or thousands of files without your consent.
• ON: KaKeKiKoKu signals your AI immediately and it starts documenting 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:

• Dismiss: marks the resource as untracked. KaKeKiKoKu will no longer require a sidecar 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 document 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 documents 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 documents it with context. When done, a new sync presents the next batch.

❓ Recently undocumented — blue

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

• Dismiss: marks the resource as untracked. KaKeKiKoKu will no longer require a sidecar 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 sidecar with an appropriate description automatically.

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

👻 Ghosts — purple

Sidecars whose original file no longer exists. Options:

• Clean: deletes the ghost sidecar.
• 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.

⚠️ Other issues — structural warnings

Minor format or configuration problems that don't corrupt anything but shouldn't be left lying around: subsections whose parent section no longer exists, 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 sidecar 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 notifies your AI. 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 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 pending-documentation policy 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.

In addition to the periodic automatic sync (its interval is configurable in Settings), KaKeKiKoKu runs a quick background analysis when it detects changes on disk. This updates the right panel and counters within seconds, so you can see issues without waiting for the timer. The periodic timer remains the one that sends results to your AI.

Center zone — Counters and navigation

Seven counters show the number of issues of each type, with the same icons and colors as the right panel. A counter only appears when it has something to count, so an empty bar means an empty project — 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 W 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 — Sync mode and AI connection

Sync mode toggle: shows Auto or Precise and switches between them with a click. This is the fastest place to change mode (the other one is Settings > Application; both write the same setting). Switching to Automatic asks for confirmation once, because Automatic only works with a client that supports channels — today that means Claude Code launched with the channels flag. If your AI is disconnected, the toggle is disabled and KaKeKiKoKu holds Precise: a push mode with nobody to push to would only hide events from you. See chapter 10 for what each mode does.

AI connection: an indicator shows whether your AI is connected:

• 🟢 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.