zigmini 0.8.0-beta.2 → 0.8.0-beta.4

package/src/hub.ts

@@ -186,6 +186,7 @@ interface QuestionItem {
 export interface ScopedQuestionFrame {
 	id: string;
 	toolCallId?: string;
+	waitForAnswer?: boolean;
 	questions: QuestionItem[];
 	askedAtMs?: number;
 	deadlineAtMs?: number;
@@ -1126,7 +1127,8 @@ export class Hub {
 			) {
 				throw new Error("turn_running");
 			}
-			if (forced) this.retireScopedQuestions(convId, sessionId);
+			// Any rotation hands main's open waits of the closed session to the next one (inbox resume); bug 72.
+			this.retireScopedQuestions(convId, sessionId);
 			try {
 				await this.requireOmo().command("close_session", { sessionId });
 				const listed = await this.requireOmo().command<{
@@ -1227,9 +1229,9 @@ export class Hub {
 		return owned;
 	}
 
-	/** What holds automatic rotation: the rotation blockers plus an unconfirmed session close. */
+	/** What holds automatic rotation: the age rotation holds plus an unconfirmed session close. */
 	private rotationHolds(conv: string): RotationBlocker[] {
-		const holds = this.rotationBlockers(conv);
+		const holds = this.rotationHoldsFor(conv, false);
 		return this.closeUncertain(conv) ? [{ kind: "session_close_unknown" }, ...holds] : holds;
 	}
 
@@ -1294,9 +1296,18 @@ export class Hub {
 		}
 	}
 
-	/** What holds a rotation now: every rotation blocker, or for a forced rotation only an unfinished main turn. */
 	private rotationHeldFor(conv: string, forced: boolean): boolean {
-		return forced ? this.rotationBlockers(conv, false).some((blocker) => blocker.kind === "main_turn") : this.rotationBlocked(conv);
+		return this.rotationHoldsFor(conv, forced).length > 0;
+	}
+
+	/**
+	 * Bugs 72 and 86: what holds a rotation now. A main turn always holds; an age or manual rotation also waits for an open
+	 * approval dialog or native question. Works, their unreported reports and inbox decisions belong to the conversation,
+	 * not the session file, so they carry over to the next session (handoff, ZGW_WORK_STATE, work update wake) and never hold.
+	 */
+	private rotationHoldsFor(conv: string, forced: boolean): RotationBlocker[] {
+		return this.rotationBlockers(conv, false).filter((blocker) =>
+			blocker.kind === "main_turn" || (!forced && (blocker.kind === "dialog" || blocker.kind === "question")));
 	}
 
 	/** Bug 72 proposal 4: the user-confirmed limit this conversation's session reached, if any. */
@@ -1334,10 +1345,10 @@ export class Hub {
 	}
 
 	/** Bug 72 proposal 4: what stays open across the rotation, so the next session owns it. */
-	private handoffOpenItems(conv: string, reason: RotationReason): string[] {
+	private handoffOpenItems(conv: string): string[] {
 		const open = this.ownedOpenDecisions(conv);
 		return [
-			reason === "size" || reason === "compactions"
+			this.workSummary(conv).length > 0
 				? "끝나지 않은 작업은 그대로 이어집니다. 목록은 ZGW_WORK_STATE와 zgw_work_list로 보고, 보고하지 않은 결과는 작업 알림으로 다시 받습니다."
 				: "",
 			...(open.length > 0
@@ -1347,7 +1358,7 @@ export class Hub {
 	}
 
 	private rotationEligible(conv: ConversationInfo): boolean {
-		if (!conv.threadId?.startsWith("/") || this.closeUncertain(conv.id) || this.rotationBlocked(conv.id)) return false;
+		if (!conv.threadId?.startsWith("/") || this.closeUncertain(conv.id) || this.rotationHeldFor(conv.id, false)) return false;
 		const started = Date.parse(this.store.getSessionMeta(conv.id).startedAt ?? conv.createdAt);
 		const used = this.store.lastSeq(conv.id, "message.user") > this.store.lastSeq(conv.id, "session.rotated");
 		if (!used) return false;
@@ -1387,7 +1398,7 @@ export class Hub {
 		return [
 			`[게이트웨이 알림] 이 대화는 새 omo 세션으로 교체됐습니다 (${this.reasonLabel(reason)}).`,
 			from ? `이전 세션의 전체 기록은 ${from} 에 남아 있습니다. 파일이 크니 필요할 때 필요한 부분만 검색해서 보세요.` : "",
-			...this.handoffOpenItems(conv, reason),
+			...this.handoffOpenItems(conv),
 			"아래는 직전 대화의 최근 부분입니다. 맥락으로만 참고하세요.",
 			"---",
 			...lines,
@@ -1786,7 +1797,8 @@ export class Hub {
 		const decision = this.decisions?.observe(owner, {
 			actionId, sourceRequestId: frame.id, method: "question", permission: false,
 			payload: { title: card.title, detail: card.detail, options: [], questions: frame.questions,
-				...(frame.toolCallId ? { toolCallId: frame.toolCallId } : {}) },
+				...(frame.toolCallId ? { toolCallId: frame.toolCallId } : {}),
+				...(frame.waitForAnswer === false ? { waitForAnswer: false } : {}) },
 			deadlineAt: frame.deadlineAtMs ?? null,
 		});
 		const open = this.openQuestionCards(owner.conv, owner.scope);

package/src/main.ts

@@ -29,6 +29,7 @@ import {
 	SYSTEM_NETWORK,
 } from "./enroll.ts";
 import { ACCESS_PATH, handleAccessApi, pingAccess, systemTailscale } from "./cli/access.ts";
+import { CHAT_TOPIC, showsThinking, THINKING_TOPIC, topicOf } from "./client-topics.ts";
 import { APK_DIR, APK_PATH, APP_DOWNLOAD_LINK_PATH, APP_VERSION_PATH, ApkSource, appVersion, createDownloadLink, DownloadLinks, serveApk } from "./app-download.ts";
 import { loadConfig } from "./config.ts";
 import { memoUpdatedData, parseMemoPatch } from "./memo-images.ts";
@@ -38,7 +39,7 @@ import { Hub, type ScopedQuestionFrame } from "./hub.ts";
 import { parseSummaryModels, SpeechSummarizer } from "./speech-summary.ts";
 import { MEDIA_MAX_BYTES, saveUpload, serveMedia } from "./media.ts";
 import { OmoClient } from "./omo/client.ts";
-import { bridgeLiveness, GenerationRouter, type GenerationEndpoint } from "./omo/generations.ts";
+import { bridgeLiveness, GenerationRouter, startupGenerations } from "./omo/generations.ts";
 import { activeRecord, readRegistry, slotUrl } from "./runtime/slots.ts";
 import { NATIVE_LIFECYCLE_PREFIX } from "./omo/lifecycle.ts";
 import { RECOVERY_RECEIPT_PREFIX } from "./omo/recovery-receipt.ts";
@@ -65,6 +66,7 @@ import { acceptUpdateConsent, requestUpdate, type UpdateApiDeps } from "./update
 import { PHASE_LABELS, readState, UPDATE_CONSENT_PATH, UPDATE_PATH, UPDATE_STATE_PATH, updateDir, UpdateWatcher } from "./update/state.ts";
 import { resolveTarget, tarEntry } from "./update/target.ts";
 import { registryUrl, UPDATE_CHECK_PATH, UPDATE_STATUS_PATH, UpdateChecker, versionAvailableEnvelope } from "./update/check.ts";
+import { MANUAL_PATH, serveManual } from "./manual.ts";
 import { clean as gcClean, GC_CLEAN_PATH, GC_PATH, type GcRoots, parseSelection as parseGcSelection, report as gcReport, systemGcDeps } from "./gc.ts";
 
 // Exit 0 so launchd (KeepAlive SuccessfulExit=false) does not restart a gateway that has no consent.
@@ -142,7 +144,6 @@ const updateApi: UpdateApiDeps = {
 	now: () => new Date(),
 };
 
-const TOPIC = "clients";
 let publish: (envelope: Envelope) => void = () => {};
 const hub = new Hub(
 	store,
@@ -189,14 +190,11 @@ function requesterId(slot: RuntimeSlot): string {
 	store.setSetting(key, id);
 	return id;
 }
-// Improvement 77: with run/runtime-slots.json the gateway connects to every listed generation; without it (or with an
-// explicit ZGW_OMO_URL, as in Docker and the tests) it has one generation, as before.
-const slotRegistry = process.env.ZGW_OMO_URL ? null : readRegistry(runtime.slotsFile);
-const endpoints: GenerationEndpoint[] = slotRegistry === null
-	? [{ slot: "a", url: config.omoUrl }]
-	: slotRegistry.slots.map((record) => ({ slot: record.slot, url: slotUrl(record) }));
+// Improvement 77: with run/runtime-slots.json the gateway connects to every listed generation; without it (or with a
+// ZGW_OMO_URL that names another OMO, as in Docker and the tests) it has one generation, as before (bug 134).
+const startup = startupGenerations(process.env.ZGW_OMO_URL, `ws://127.0.0.1:${runtime.ports.bridge}`, () => readRegistry(runtime.slotsFile));
 let connectionGeneration = 0;
-const omo = new GenerationRouter(endpoints, slotRegistry === null ? "a" : activeRecord(slotRegistry).slot, {
+const omo = new GenerationRouter(startup.endpoints, startup.active, {
 	connect: (endpoint, handlers) => new OmoClient(endpoint.url, omoToken, handlers, requesterId(endpoint.slot)),
 	liveness: (endpoint) => bridgeLiveness(endpoint.url, omoToken),
 	log: (line) => console.log(line),
@@ -397,6 +395,7 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 				// question cannot race into a phone notification between those adjacent frames.
 				questionNotifications.setWebPresence(ws, true);
 			}
+			if (!showsThinking(msg.data?.client)) ws.unsubscribe(THINKING_TOPIC);
 			const state = hub.snapshot();
 			const snapshot = { ...state, approvals: omoCheckNotifications.filterApprovals(state.approvals) };
 			// While omo is reconnecting, Hub intentionally clears its in-memory question cards until
@@ -628,6 +627,7 @@ async function handle(req: Request, srv: Server<Conn>, trusted: boolean): Promis
 		const response = await handleProfileIcon(req, url, trusted, { icon: profileIcon, profile: () => readProfile(store), publish: (e) => publish(e) });
 		if (response) return response;
 	}
+	if (url.pathname === MANUAL_PATH) return serveManual(req, url);
 	// Plan Todo 23: the update button. The app port may ask too, but never for an update that needs a new consent.
 	if (url.pathname === UPDATE_PATH && req.method === "POST") {
 		const body = await req.json().catch(() => null) as { origin?: unknown } | null;
@@ -806,7 +806,10 @@ async function routeApi(req: Request, url: URL): Promise<Response> {
 
 const websocket: WebSocketHandler<Conn> = {
 	open(ws) {
-		if (!ws.data.notifyOnly) ws.subscribe(TOPIC);
+		if (!ws.data.notifyOnly) {
+			ws.subscribe(CHAT_TOPIC);
+			ws.subscribe(THINKING_TOPIC);
+		}
 		if (ws.data.trusted && !ws.data.notifyOnly) ws.subscribe(TRUSTED_TOPIC);
 		const id = ws.data.deviceId;
 		if (id) {
@@ -837,8 +840,9 @@ publish = (e) => {
 	if (!omoCheckNotifications.allow(e)) return;
 	questionNotifications.onEnvelope(e);
 	const text = JSON.stringify(e);
-	trustedServer.publish(TOPIC, text);
-	lanServer?.publish(TOPIC, text);
+	const topic = topicOf(e.type);
+	trustedServer.publish(topic, text);
+	lanServer?.publish(topic, text);
 	// A decision change can change a work's 입력 대기 state (its open decisions, or its status after a delivered answer).
 	if (e.type === "activity.updated" || e.type === "conversation.created" || e.type === "decision.updated") workStatus.schedule();
 };

package/src/manual.ts

@@ -0,0 +1,31 @@
+import { join } from "node:path";
+
+/**
+ * The user manual (docs/manual.md, docs/manual.ko.md) for the web 설정 "매뉴얼" button and the app's work status screen.
+ * Read only, on the web port and, behind the app device gate, on the app port. Korean is the default language.
+ */
+export const MANUAL_PATH = "/api/manual";
+export const MANUAL_DIR = join(import.meta.dir, "..", "docs");
+export type ManualLang = "ko" | "en";
+
+/** The `lang` query value as a language: missing or empty is Korean; anything but `ko` or `en` is null. */
+export function manualLang(value: string | null): ManualLang | null {
+	if (value === null || value === "" || value === "ko") return "ko";
+	return value === "en" ? "en" : null;
+}
+
+export function manualFile(lang: ManualLang): string {
+	return lang === "en" ? "manual.md" : "manual.ko.md";
+}
+
+/** `GET /api/manual?lang=ko|en`: the Markdown text; 400 for another language, 404 with a hint when the file is missing. */
+export async function serveManual(req: Request, url: URL, dir: string = MANUAL_DIR): Promise<Response> {
+	if (req.method !== "GET") return Response.json({ error: "method_not_allowed" }, { status: 405 });
+	const lang = manualLang(url.searchParams.get("lang"));
+	if (lang === null) return Response.json({ error: "unknown_lang", message: "lang은 ko 또는 en입니다." }, { status: 400 });
+	const file = Bun.file(join(dir, manualFile(lang)));
+	if (!(await file.exists())) {
+		return Response.json({ error: "manual_missing", message: "이 설치에는 매뉴얼 파일이 없습니다. 게이트웨이를 업데이트하세요." }, { status: 404 });
+	}
+	return new Response(file, { headers: { "content-type": "text/markdown; charset=utf-8", "cache-control": "no-cache", "content-language": lang } });
+}

package/src/omo/generations.ts

@@ -1,4 +1,5 @@
 import type { RuntimeSlot } from "../runtime/paths.ts";
+import { activeRecord, type SlotRegistry, slotUrl } from "../runtime/slots.ts";
 import type { OmoClientHandlers, OmoEvent, OmoStatus } from "./client.ts";
 
 /**
@@ -55,18 +56,43 @@ type Listed = { sessionId?: unknown; sessionPath?: unknown };
 
 const LIVENESS_TIMEOUT_MS = 5000;
 
+/**
+ * Bug 134: an installed gateway gets ZGW_OMO_URL from config.env, and it names this Mac's own slot a bridge. That value
+ * must not hide run/runtime-slots.json: when the update handoff restarts the gateway, the generation that still holds the
+ * sessions can be slot b. The registry is used unless ZGW_OMO_URL names another OMO (Docker, tests).
+ */
+export function startupGenerations(explicitUrl: string | undefined, localUrl: string, registry: () => SlotRegistry | null): { endpoints: GenerationEndpoint[]; active: RuntimeSlot } {
+	const url = explicitUrl || localUrl;
+	const listed = isLocalBridge(url, localUrl) ? registry() : null;
+	if (listed === null) return { endpoints: [{ slot: "a", url }], active: "a" };
+	return { endpoints: listed.slots.map((record) => ({ slot: record.slot, url: slotUrl(record) })), active: activeRecord(listed).slot };
+}
+
+function isLocalBridge(url: string, localUrl: string): boolean {
+	if (!URL.canParse(url)) return false;
+	const given = new URL(url);
+	const local = new URL(localUrl);
+	return given.protocol === local.protocol && given.port === local.port && given.pathname === "/" && given.search === "" &&
+		(given.hostname === "127.0.0.1" || given.hostname === "localhost");
+}
+
 /**
  * Bug 118: after a bridge restart the previous OMO host can still hold its claim on a session file for a moment (the
  * bridge's SIGTERM ends the host without waiting for it). The new host answers open_session with `session_path_in_use`
  * and `errorData.retry_after_ms` until that claim is gone; OMO documents the refusal as retryable. The open waits it out
  * for at most SESSION_PATH_WAIT_MS and never takes the path from the other host.
+ * Bug 134: `session_held` (a live holder outside this host's daemon family, e.g. a draining older generation) is waited
+ * out the same way; it carries no retry hint, so the open waits SESSION_PATH_RETRY_MS between tries.
  */
 export const SESSION_PATH_WAIT_MS = 60_000;
 export const SESSION_PATH_RETRY_MS = 2000;
 
-/** Milliseconds to wait before reopening after this error, or null when the error is not a held session path. */
+/** Milliseconds to wait before reopening after this error, or null when the error is not a held session. */
 export function sessionPathRetryMs(error: unknown): number | null {
-	if (typeof error !== "object" || error === null || (error as { code?: unknown }).code !== "session_path_in_use") return null;
+	if (typeof error !== "object" || error === null) return null;
+	const code = (error as { code?: unknown }).code;
+	if (code === "session_held") return SESSION_PATH_RETRY_MS;
+	if (code !== "session_path_in_use") return null;
 	const data = (error as { errorData?: unknown }).errorData;
 	const hint = typeof data === "object" && data !== null ? (data as { retry_after_ms?: unknown }).retry_after_ms : undefined;
 	return typeof hint === "number" && hint > 0 ? hint : SESSION_PATH_RETRY_MS;

package/src/store.ts

@@ -215,7 +215,7 @@ export interface WorkStartRequest extends WorkCommandRequest {
 export type WorkReport = Pick<WorkUpdate, "sourceKey" | "kind" | "commandSeq" | "summary" | "details">;
 
 export class WorkStoreError extends Error {
-	constructor(readonly code: "work_not_found" | "command_not_found" | "request_key_conflict" | "report_conflict" | "invalid_report_command" | "invalid_delivery_transition" | "invalid_publish" | "publish_conflict" | "unresolved_work_commands" | "required_decisions_pending" | "question_without_decision", readonly ids: readonly string[] = []) {
+	constructor(readonly code: "work_not_found" | "command_not_found" | "request_key_conflict" | "report_conflict" | "invalid_report_command" | "invalid_delivery_transition" | "invalid_publish" | "publish_conflict" | "unresolved_work_commands" | "required_decisions_pending" | "question_without_decision" | "invalid_replacement_details", readonly ids: readonly string[] = []) {
 		super(code);
 	}
 }
@@ -420,8 +420,12 @@ export function replacementQuestionPayload(payload: Record<string, unknown>): Re
 		options: Array.isArray(withIds.options) ? withIds.options : [] };
 }
 
-/** Closed bindings whose question still takes an answer, delivered to the owner as a follow-up command. */
-export const RESUMABLE_CLOSED: ReadonlySet<string> = new Set(["report_only", "main_released"]);
+/**
+ * Closed bindings whose question still takes an answer, delivered to the owner as a follow-up command. Bug 127:
+ * async_wait_closed (a waitForAnswer false question whose native wait ended) and recheck_incomplete (a recheck turn
+ * ended without a replacement; the question stands as asked). A permission is never resumed (submitDecision, info).
+ */
+export const RESUMABLE_CLOSED: ReadonlySet<string> = new Set(["report_only", "main_released", "async_wait_closed", "recheck_incomplete"]);
 
 /** Checks structural completeness, not the semantic appropriateness of a historical answer. */
 function completeDecisionAnswer(method: DecisionMethod, payload: unknown, response: unknown): boolean {
@@ -1374,7 +1378,14 @@ export class Store {
 			if (command && report.kind !== "observation" && (command.delivery === "pending" || command.delivery === "sending" || command.delivery === "unknown")) {
 				this.setWorkCommandDelivery(command.id, "accepted", { disposition: "work_report" });
 			}
-			if (command && report.kind === "question" && object(report.details) && typeof report.details.replaces_decision_id === "string") {
+			// Bug 127: a question report on a recheck command must carry its replacement as an object; anything else would be
+			// accepted without replacing and leave the old question recheck-only.
+			const replacing = object(report.details) && typeof report.details.replaces_decision_id === "string";
+			if (command && report.kind === "question" && !replacing && object(command.payload) &&
+				(command.payload.decision_operation === "recheck" || command.payload.decision_operation === "request_permission")) {
+				throw new WorkStoreError("invalid_replacement_details", [workId]);
+			}
+			if (command && report.kind === "question" && replacing) {
 				this.replaceDecisionFromReport({
 					scope: `work:${workId}`, sourceSessionPath: work.sessionPath,
 					reportId: report.sourceKey, commandId: command.id, details: report.details,

package/src/work.ts

@@ -85,6 +85,8 @@ const REPORT_RULE = "Report completed or failed with the highest command_seq of
 const QUESTION_WITHOUT_DECISION = "No inbox question is open for this work. Ask the user with ask_user_question first " +
 	"(waitForAnswer true for a required confirmation, which then needs no kind=question report; " +
 	"waitForAnswer false only if the work may continue without the answer and you also report), then send kind=question again. A kind=question report alone creates no inbox question.";
+const INVALID_REPLACEMENT_DETAILS = "This report answers a recheck, so details must be a JSON object, not a string: " +
+	"{replaces_decision_id, submission_id, and replacement:{method,payload,required} or replacement_decision_id}. Send the report again with details as an object.";
 function envelope(command: WorkCommand): string {
 	return PREFIX + JSON.stringify({ version: 1, work_id: command.workId, command_id: command.id, command_seq: command.seq, kind: command.kind, payload: command.payload, report_rule: REPORT_RULE });
 }
@@ -155,7 +157,9 @@ export class WorkRouter {
 		} catch (error) {
 			if (error instanceof RoutingError) return Response.json({ error: error.code }, { status: error.status });
 			if (error instanceof WorkStoreError) return Response.json({ error: error.code, ids: error.ids,
-				...(error.code === "question_without_decision" ? { detail: QUESTION_WITHOUT_DECISION } : {}) }, { status: 409 });
+				...(error.code === "question_without_decision" ? { detail: QUESTION_WITHOUT_DECISION } : {}),
+				...(error.code === "invalid_replacement_details" ? { detail: INVALID_REPLACEMENT_DETAILS } : {}) },
+			{ status: error.code === "invalid_replacement_details" ? 400 : 409 });
 			if (error instanceof DecisionStoreError) return Response.json({ error: error.code }, {
 				status: error.code === "decision_not_found" ? 404 : error.code.startsWith("invalid_") ? 400 : 409,
 			});
@@ -601,7 +605,7 @@ export class WorkRouter {
 			} catch (error) {
 				// The live report call already showed the worker this refusal; recovery skips the entry.
 				// Unresolved commands retain their receipt state; completion needs a new valid report.
-				if (error instanceof WorkStoreError && ["question_without_decision", "unresolved_work_commands"].includes(error.code)) continue;
+				if (error instanceof WorkStoreError && ["question_without_decision", "unresolved_work_commands", "invalid_replacement_details"].includes(error.code)) continue;
 				if (!(error instanceof WorkStoreError) || error.code !== "required_decisions_pending") throw error;
 				deferred = Math.min(deferred, index);
 			}

package/web/app.js

@@ -41,6 +41,7 @@ import { createEnrollment, NO_DEVICES_LINE, REVOKE_ARMED_LABEL, REVOKE_LABEL } f
 import { canUpdate, checkFailedLine, noticeLine, parseNotice, progressLine, questionGate, resultLine, UPDATE_CHECK_PATH, UPDATE_CONSENT_PATH, UPDATE_PATH, UPDATE_STATE_PATH, UPDATE_STATUS_PATH, updateStep, updateView } from "./update.js";
 import { createAppDownload } from "./app-download.js";
 import { cleanRequest, cleanResultLine, GC_CLEAN_PATH, GC_PATH, gcView } from "./gc.js";
+import { manualFailureText, manualLinkLang, manualUrl, otherLang } from "./manual.js";
 
 const $ = (id) => document.getElementById(id);
 const state = {
@@ -3689,4 +3690,93 @@ settings.toggle.onclick = () => (settings.open ? closeSettings() : openSettings(
 settings.close.onclick = closeSettings;
 enrollEls.renew.onclick = () => void enrollment.renew();
 
+// 설정 "매뉴얼": GET /api/manual (Korean first) rendered with the chat Markdown renderer; the first-line language links
+// and the header button switch to the other language in place.
+const manualEls = { el: $("manual"), open: $("manual-open"), close: $("manual-close"), title: $("manual-title"), lang: $("manual-lang"), status: $("manual-status"), body: $("manual-body") };
+const manualView = { open: false, lang: "ko", load: 0 };
+
+function showManualStatus(text, error = false) {
+	manualEls.status.textContent = text;
+	manualEls.status.classList.toggle("error", error);
+	manualEls.status.hidden = text === "";
+}
+
+async function loadManual(lang) {
+	const load = ++manualView.load;
+	manualView.lang = lang;
+	manualEls.lang.textContent = otherLang(lang) === "en" ? "English" : "한국어";
+	manualEls.el.lang = lang;
+	showManualStatus("매뉴얼을 불러오는 중입니다.");
+	let status = 0;
+	let text = "";
+	try {
+		const res = await fetch(manualUrl(lang));
+		status = res.status;
+		if (res.ok) text = await res.text();
+	} catch (error) {
+		console.warn("manual:", error);
+	}
+	if (load !== manualView.load) return;
+	if (text === "") {
+		manualEls.body.innerHTML = "";
+		showManualStatus(manualFailureText(status), true);
+		return;
+	}
+	showManualStatus("");
+	renderMarkdown(manualEls.body, text);
+	manualEls.body.scrollTop = 0;
+}
+
+function openManual() {
+	if (manualView.open) return;
+	manualView.open = true;
+	manualEls.el.hidden = false;
+	manualEls.open.setAttribute("aria-expanded", "true");
+	manualEls.title.focus();
+	void loadManual(manualView.lang);
+}
+
+function closeManual() {
+	if (!manualView.open) return;
+	manualView.open = false;
+	manualView.load++;
+	manualEls.el.hidden = true;
+	manualEls.open.setAttribute("aria-expanded", "false");
+	manualEls.open.focus();
+}
+
+manualEls.open.onclick = openManual;
+manualEls.close.onclick = closeManual;
+manualEls.lang.onclick = () => void loadManual(otherLang(manualView.lang));
+manualEls.body.addEventListener("click", (ev) => {
+	const link = ev.target instanceof Element ? ev.target.closest("a") : null;
+	const lang = manualLinkLang(link?.getAttribute("href"));
+	if (lang === null) return;
+	ev.preventDefault();
+	void loadManual(lang);
+});
+manualEls.el.addEventListener("click", (ev) => {
+	if (ev.target === manualEls.el) closeManual();
+});
+manualEls.el.addEventListener("keydown", (ev) => {
+	if (ev.isComposing) return;
+	if (ev.key === "Escape") {
+		ev.preventDefault();
+		closeManual();
+		return;
+	}
+	if (ev.key !== "Tab") return;
+	const focusable = [...manualEls.el.querySelectorAll(FOCUSABLE)].filter((node) => node.offsetParent !== null);
+	if (focusable.length === 0) return;
+	const first = focusable[0];
+	const last = focusable.at(-1);
+	if (ev.shiftKey && (document.activeElement === first || document.activeElement === manualEls.title)) {
+		ev.preventDefault();
+		last.focus();
+	} else if (!ev.shiftKey && document.activeElement === last) {
+		ev.preventDefault();
+		first.focus();
+	}
+});
+
 connect();

package/web/index.html

@@ -122,6 +122,7 @@
     <div class="settings-card">
       <header class="settings-head">
         <h2 class="settings-title" id="settings-title" tabindex="-1">설정</h2>
+        <button type="button" class="text-btn" id="manual-open" title="사용자 매뉴얼: 화면, 단축키, 기능" aria-haspopup="dialog" aria-expanded="false" aria-controls="manual">매뉴얼</button>
         <button type="button" class="icon-btn settings-close" id="settings-close" aria-label="설정 닫기" title="닫기 (Esc)">×</button>
       </header>
       <div class="settings-body">
@@ -185,6 +186,17 @@
       </div>
     </div>
   </aside>
+  <aside class="settings manual" id="manual" role="dialog" aria-labelledby="manual-title" hidden>
+    <div class="settings-card manual-card">
+      <header class="settings-head">
+        <h2 class="settings-title" id="manual-title" tabindex="-1">매뉴얼</h2>
+        <button type="button" class="text-btn" id="manual-lang">English</button>
+        <button type="button" class="icon-btn settings-close" id="manual-close" aria-label="매뉴얼 닫기" title="닫기 (Esc)">×</button>
+      </header>
+      <p class="manual-status" id="manual-status" role="status" aria-live="polite" hidden></p>
+      <div class="manual-body msg-text" id="manual-body"></div>
+    </div>
+  </aside>
   <aside class="dev" id="dev">
     <header class="dev-head">
       <span>이벤트</span>

package/web/manual.d.ts

@@ -0,0 +1,7 @@
+export type ManualLang = "ko" | "en";
+export declare const MANUAL_PATH: string;
+export declare const MANUAL_MISSING_TEXT: string;
+export declare function manualUrl(lang: string): string;
+export declare function otherLang(lang: string): ManualLang;
+export declare function manualLinkLang(href: string | null | undefined): ManualLang | null;
+export declare function manualFailureText(status: number): string;

package/web/manual.js

@@ -0,0 +1,29 @@
+// The user manual view of 설정 "매뉴얼": decisions only, with no DOM, so test/unit/manual.test.ts and the mutation run
+// drive them directly; app.js fetches GET /api/manual and renders the Markdown with the chat renderer.
+
+export const MANUAL_PATH = "/api/manual";
+export const MANUAL_MISSING_TEXT = "이 게이트웨이 버전에는 매뉴얼이 없습니다. 게이트웨이를 업데이트하면 볼 수 있습니다.";
+
+export function manualUrl(lang) {
+	return `${MANUAL_PATH}?lang=${lang === "en" ? "en" : "ko"}`;
+}
+
+export function otherLang(lang) {
+	return lang === "en" ? "ko" : "en";
+}
+
+/** The language a rendered link switches to: the manuals' first line links manual.md (English) and manual.ko.md (Korean). */
+export function manualLinkLang(href) {
+	if (typeof href !== "string") return null;
+	const file = href.split(/[?#]/)[0].split("/").pop();
+	if (file === "manual.md") return "en";
+	if (file === "manual.ko.md") return "ko";
+	return null;
+}
+
+/** The line for a failed load: [status] is the HTTP status, or 0 when the request itself failed. */
+export function manualFailureText(status) {
+	if (status === 404) return MANUAL_MISSING_TEXT;
+	if (status === 0) return "매뉴얼을 불러오지 못했습니다. 게이트웨이 연결을 확인하세요.";
+	return `매뉴얼을 불러오지 못했습니다 (HTTP ${status}).`;
+}

package/web/style.css

@@ -423,6 +423,11 @@ button { font: inherit; color: inherit; cursor: pointer; }
 .gc-message:empty { display: none; }
 .gc-message.error { color: #f38b8d; }
 .gc-actions { display: flex; justify-content: flex-end; }
+.settings.manual { z-index: 31; }
+.manual-card { width: min(100%, 760px); height: 100%; }
+.manual-status { margin: 0; padding: 12px 16px 0; font-size: 13px; color: var(--muted); }
+.manual-status.error { color: #f38b8d; }
+.manual-body { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; padding: 16px; }
 @media (max-width: 640px) {
 	.settings { padding: 0; }
 	.settings-card { width: 100%; height: 100dvh; max-height: none; border: 0; border-radius: 0; }