# KaKeKiKoKu Studio — local HTTP access

The human starts KaKeKiKoKu Studio before the AI uses it. Use the local command
bridge at `http://localhost:5050/api/agent`. It runs on the same computer as Studio. An AI whose
shell runs in a container, remote host or separate sandbox may not reach this
loopback address; use a local execution tool with the necessary network permission.
Do not invent a tunnel, configure MCP, start another server, or change the port.
If Studio is unavailable, ask the human to start it and confirm its local address.

## Start of each conversation

1. Send an HTTP POST with `Content-Type: application/json` and this JSON body:
   `{"action":"initialize","protocolVersion":1,"client":"your IDE or agent name"}`.
2. Parse the JSON response and keep its `sessionId` for this conversation. `client` is an optional,
   self-declared label, not authenticated identity. Never initialize per command.
3. Run `open list` as the first command, using POST and JSON at the same URL:
   `{"action":"run","sessionId":"returned-id","command":"open list"}`.
   Use a JSON serializer; command quotes, backslashes and newlines need JSON escaping.
   The response is plain text. Read the body even when the HTTP status is not 200.
   Wait for each command before sending another that depends on it.
4. Next run `help` with the same `run` envelope, then open only projects returned
   by `open list` that this task needs.
   If the list is empty, proceed normally; the human may open projects later.
   Never assume the current working directory is a KaKeKiKoKu project.

Use an available local HTTP tool, or a shell with PowerShell `Invoke-WebRequest`,
Python's standard HTTP library, or `curl`. Keep normal tool permission checks.
There is no extra CLI or MCP process to install. Fetch only needed `help <topic>`
pages for the command language and reading rules. `initialize` reports request
and response limits; `maxResponseChars` counts UTF-16 code units in the command's
plain-text response. Respect these limits and follow the help for large results.
GET at the same URL returns discovery information; add `?instructions=agents` or
`?instructions=claude` to download these instructions for this Studio instance.

## Project knowledge

- `.wuniq` files: never use native Read/Edit/Write. Use `read`, `edit`, `new`, `search`.
- Before code work, read the folder sidecar first, then the relevant file sidecars.
- Capture human decisions, constraints and rationale in sidecars immediately.
- Use named subsections for distinct topics; append only to the same topic.
- After changing project files or context, run `sync` and follow its instructions.
- Use native tools for real project files. `read` retrieves knowledge, not source code.
- Coordinate edits with other clients and the human; do not write the same resource
  concurrently. Shared project state does not provide transaction isolation.
- For product or Web questions, run `help kakekikoku`. Use `current` for the human's
  Web view associated with projects opened by this conversation.

## Session recovery

Sessions expire after 24 hours without requests and whenever Studio restarts.
HTTP 410 with `SESSION_EXPIRED` means this request was not forwarded. Initialize
again, run `open list`, and open the projects still needed. Reads/project state are
shared with the Web and other clients, not isolated by this session identifier.
After a lost response, timeout or server restart, inspect the affected state before
repeating a mutation: the original command may already have completed. No retries
are performed by the bridge. Set the HTTP client's timeout to at least 610 seconds
for long commands; the bridge's execution timeout is 600 seconds.

At the end, optionally POST `{"action":"close","sessionId":"returned-id"}`.
This retires only the HTTP identity; accepted commands may still finish.
The language command `close` closes a shared
project and affects other clients; do not use it just to disconnect.

Studio must remain running. HTTP does not auto-launch it, provide background MCP
heartbeats/channel notifications, or expose development commands such as
`dev recompile`. Run `sync` at appropriate checkpoints to discover drift.
The local API trusts local processes; the session ID is not an authentication token.

If this file already contains project instructions, merge this section and preserve them.