@c0sc0s/codex-tags 0.5.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "codex-tags",
+  "version": "0.5.0+codex.20260907085903",
+  "description": "Add tag-aware session browsing and local content search to the Codex desktop sidebar.",
+  "author": {
+    "name": "Codex Tags contributors"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Codex Tags",
+    "shortDescription": "Tag, filter, and search local Codex sessions.",
+    "longDescription": "Codex Tags installs a reversible local enhancement for the official Codex desktop app. It renders structured session tags, supports custom colors and optional AI classification descriptions, provides a searchable Tags dashboard, and keeps session content on the local machine.",
+    "developerName": "Codex Tags contributors",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Use $doctor to check whether Codex Tags is healthy.",
+      "Use $initial to tag my active Codex sessions using my configured tags.",
+      "Use $rename to name this session with the best matching configured tag."
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Codex Tags engineering guide
+
+## Project overview
+
+Codex Tags is a reversible macOS enhancement for the official Codex desktop app. It starts Codex with a loopback-only Chrome DevTools Protocol endpoint, indexes local session text, and injects a bundled TypeScript/Preact UI into the renderer. It never edits the signed Codex bundle or `app.asar`.
+
+## Read before changing code
+
+| Task | Required document |
+| --- | --- |
+| Local setup, code ownership, build, hot-apply, or debugging | `docs/development.md` |
+| Packaging, release, public distribution, or user installation | `docs/distribution.md` |
+| Runtime boundaries and data flow | `docs/architecture.md` |
+| Architecture evolution, refactoring sequence, or adding a major capability | `docs/roadmap.md` |
+| Title and controller/runtime contracts | `docs/protocol.md` |
+| Codex-version compatibility work | `docs/compatibility.md` |
+
+## Hard constraints
+
+- Edit source in this repository only. Never edit the installed copy under `~/Library/Application Support/Codex Sidebar Tags`.
+- Keep the official Codex application bundle, code signature, tasks, and authentication data untouched.
+- Keep session content local. Never log conversation bodies or send them to a remote service.
+- Keep private Codex selectors inside `runtime/src/injected/codex-dom-adapter.ts`.
+- The injected runtime must not fetch remote scripts, styles, or assets.
+- Do not hand-edit `runtime/dist/injected.js`; regenerate it with `npm run build` and commit it with its source.
+- Increment `RUNTIME_VERSION` after injected behavior changes. Use the plugin cachebuster update flow for plugin releases.
+
+## Required verification
+
+```bash
+npm run build
+npm run check
+npm run typecheck
+npm test
+node scripts/manage.mjs install
+node scripts/manage.mjs apply
+node scripts/manage.mjs status
+node runtime/qa-runtime.mjs
+git diff --check
+```
+
+`npm run verify` is the local shortcut for the first four commands. `npm run dev:apply` is the supported build → install → hot-apply development loop.
+
+`apply` requires Codex to already be running with the owned local CDP endpoint. Follow `docs/development.md` for first-run setup and failure handling.

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 0.5.0 — 2026-09-07
+
+Initial public early release. Automated verification and packed-consumer tests pass; clean-account GUI and hook-trust acceptance remain pending.
+
+- Use the dedicated Codex Tags.app launcher with its own icon; remove automatic launch takeover and clean up legacy LaunchAgents on installation. Running non-debuggable apps are left untouched.
+- Exclude subagent and guardian-review sessions from the active catalog, dashboard counts and search scope; retain standalone tasks and clean stale cached entries.
+- Add an original project logo, linked English/Chinese GitHub homepages and concise development, architecture and release documentation.
+- Merge legacy cached local IDs without duplicate sessions; index standard user message records and rebuild older extraction caches automatically.
+- Reject symlink installation destinations before lifecycle mutation and keep environment files out of package artifacts.
+- Default the public CLI to installation, with explicit three-hook authorization guidance and nonzero exit status for incomplete activation.
+- Validate arguments, serialize public lifecycle mutations, resolve hoisted npm dependencies, stop old runtime code before updating, and preserve unrelated launchers and marketplaces.
+- Check current UI versions, navigation availability, controller ownership, settings, catalog and index health using one readiness contract.
+- Read active local sessions independently of sidebar expansion, use actual update timestamps, and navigate catalog-only results through the app's thread links.
+- Add tag description/color editing, deletion confirmation/undo, reserved fallback handling and consistent 32-character names; protect settings inputs and menus from background refreshes.
+- Add isolated packed-consumer/native-runtime smoke tests, dashboard interaction regression tests, and macOS CI.
+
+All notable changes to Codex Tags are documented here. Versions follow Semantic Versioning.
+
+### Included capabilities
+
+- Reduced built-in tags to Feature, Bug, Design, and Research with English classification guidance; preserved saved user definitions and custom tags.
+- Replaced the management skill with three English user skills: Doctor, Initial, and Rename, using native Codex task tools for agent-driven classification and naming.
+- Standardized generated titles as `[Tag]Title` without date metadata while preserving legacy title parsing; shared live tag/description context between skills and first-prompt hooks and expanded the context budget for the full supported vocabulary.
+- Added a dedicated macOS launcher with foreign-port protection and reversible lifecycle management.
+- Added a publishable `@c0sc0s/codex-tags` CLI with one-command install, enable, disable, status, doctor, update, and reversible uninstall flows.
+- Delegated naming-hook registration to the official Codex Marketplace and Plugin CLI instead of mutating private configuration or trust records.
+- Replaced the AppleScript launcher compiler dependency with a minimal atomic macOS application bundle.
+- Made clean-machine testing deterministic by removing Codex Tags renderer caches and hook markers during explicit `uninstall --purge`.
+- Added a native-aligned Tags rail above Pinned for filtering visible sidebar sessions without opening the dashboard.
+- Kept the compact rail and dashboard on one filter state while preserving focus, horizontal position, collapsed-group indexing, and reversible native row visibility.
+- Added optional classification descriptions and arbitrary six-digit colors to tag definitions.
+- Added six curated color presets plus a native color picker to tag creation.
+- Upgraded tag settings to schema v2 with automatic legacy tone migration and passed tag descriptions, but not colors, into the first-session naming context.
+- Redesigned tag settings as a compact native-aligned editor with a unified color control and a lightweight, divided configuration list.
+- Reduced sidebar color noise with progressive tag emphasis: quiet at rest, stronger on hover, strongest for the selected filter, and no repeated row labels while a concrete tag is active.
+- Made the controller-owned atomic settings repository authoritative while retaining renderer storage only for first-install migration and last-known caching.
+- Added a protocol-v1 envelope and centralized controller router for settings and search messages.
+- Split process ownership, target injection, settings, title decoration, sidebar filtering, dashboard rendering, session bindings, styles, and host refresh lifecycle into independently owned modules.
+- Removed the injected runtime's permissive TypeScript boundary and added fail-closed runtime configuration validation plus service/contract tests.
+- Made modal exit and observer refresh converge when Chromium suspends animation frames in an occluded Electron window.
+- Rebuild stale owned overlays after Codex replaces a renderer execution context while retaining host DOM.
+- Replaced the ambiguous four-tile Tags launcher icon with a native-weight tag glyph.
+- Added English and Simplified Chinese UI resources that follow Codex's active language and update without restarting the injected runtime.
+
+## 0.3.0 — 2026-09-04
+
+- Added locally bundled Motion animations for dashboard entry and exit, menu and tab transitions, search feedback, and interaction states with reduced-motion support.
+- Replaced full conversation transfer to the renderer with asynchronous local search requests.
+- Added a persistent, incremental SQLite FTS5 index with Chinese substring search support.
+- Added a persistent CDP binding for search requests and bounded result delivery.
+- Added loading and failure states while keeping title and tag matches immediate.
+- Added search-index lifecycle tests and packaged the SQLite runtime dependency during installation.
+- Added a plugin-native first-prompt hook that gives the Codex agent the current tag vocabulary and naming protocol without editing session data.
+- Added versioned tag-settings synchronization and lifecycle tests for new versus resumed sessions.
+
+## 0.2.0 — 2026-09-04
+
+- Migrated the injected runtime build to TypeScript, Preact, and esbuild.
+- Split strict session models, dashboard state, search/ranking, result rendering, and Codex DOM discovery into independent modules.
+- Added title/content search tests, snippet selection coverage, and typed build validation.
+- Bundled the browser runtime as an installable local artifact with no runtime package-manager or network dependency.
+- Preserved the existing Tags UI, IME handling, sorting, filtering, navigation, and reversible native DOM behavior.
+- Added dedicated local-development/debugging and distribution/installation guides, plus an agent-readable project entry point.
+
+## 0.1.0 — 2026-09-04
+
+- Productized the existing sidebar enhancement as a Codex plugin source tree.
+- Added reproducible install, status, enable, apply, restore, and uninstall commands.
+- Added controller ownership checks and safe handling for foreign CDP port occupants.
+- Replaced repeated full synchronization with health polling and changed-content refreshes.
+- Added expiring Session file discovery so newly created sessions can be indexed.
+- Preserved native title DOM and accessibility attributes during reversible enhancement.
+- Added architecture, protocol, compatibility, and contributor documentation.

package/README.md

@@ -0,0 +1,87 @@
+<p align="center"><img src="assets/banner.png" alt="Codex Tags — Less scrolling. More finding." width="100%"></p>
+<p align="center"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p>
+<p align="center"><a href="#get-started">Get started</a> · <a href="#commands">Commands</a> · <a href="docs/development.md">Development</a> · <a href="docs/architecture.md">Architecture</a></p>
+
+An independent, local-first enhancement for Codex: organize sessions with tags, search conversation text, and give the agent your classification rules.
+
+**macOS · Node.js 22+ · English / 简体中文**
+
+> **Early release** — Automated checks pass. Clean-account cold-start and manually trusted first-turn naming still need full end-to-end acceptance; see [verification coverage](docs/compatibility.md).
+
+## Features
+
+- **Native-aligned sidebar:** tag filtering, quiet title labels, and a Tags dashboard.
+- **Local search:** titles and indexed user/assistant text, with highlighted matches.
+- **Your vocabulary:** Feature, Bug, Design, Research defaults; custom colors and optional classification descriptions.
+- **Agent-assisted naming:** `[Tag]Title`, without dates. First prompts receive current classification guidance.
+- **Three plugin skills:** `doctor` checks health; `initial` classifies existing active sessions; `rename` names the current session.
+- **English and Chinese UI:** follows Codex's language without translating user-defined tags.
+
+## Get started
+
+### 1. Install the CLI and plugin
+
+Finish active tasks and quit Codex if it is open without Tags, then run:
+
+```bash
+npx @c0sc0s/codex-tags@latest
+```
+
+### 2. Authorize the hooks
+
+Open **Codex → Plugins → Codex Tags** and review/trust **SessionStart**, **UserPromptSubmit**, and **SessionEnd**.
+
+**Next time:** open `~/Applications/Codex Tags.app` and pin it to the Dock. It launches the official app, not a second Codex installation. No automatic restart or launch supervisor. Naming is agent-assisted, not a guaranteed title rewrite.
+
+<details>
+<summary>Develop or install from source</summary>
+
+```bash
+git clone https://github.com/c0sc0s/codex-tags.git
+cd codex-tags
+npm ci
+npm run verify
+node bin/codex-tags.mjs install
+```
+
+Then authorize the same three hooks above.
+
+</details>
+
+## Commands
+
+Run `npx @c0sc0s/codex-tags@latest <command>`. From source: `node bin/codex-tags.mjs <command>`.
+
+| Command | Effect |
+| --- | --- |
+| `install`, `on`, `enable` | Install this package version and activate all components |
+| `off`, `restore`, `disable` | Stop injection and remove the naming plugin; keep data |
+| `status` / `doctor` | Inspect state / diagnose readiness without changes |
+| `update` | Install the invoked version; use `@latest` to fetch the newest |
+| `uninstall` | Remove owned components and index; keep tag settings |
+| `uninstall --purge` | Also remove settings and owned caches |
+
+Operational commands support `--json`. Hook trust remains a manual Codex security decision.
+
+## Privacy and compatibility
+
+The CLI installs local code and registers the plugin through Codex's plugin commands. It does **not** patch the signed app, edit transcripts, or change authentication data. A local SQLite index supplies bounded matching snippets to the UI.
+
+Injection relies on a loopback debugging endpoint and private Codex DOM/database interfaces—not an official sidebar extension API. Future Codex updates can require adapter changes. Debugging access is powerful; use only on a trusted machine. See [verified coverage and limitations](docs/compatibility.md).
+
+## Development
+
+```bash
+npm run dev:apply   # build → refresh installed files → hot-apply
+npm run verify     # build, syntax, types, regression tests
+npm run test:package
+```
+
+The fast loop requires an already activated, debug-enabled app. No HMR server is used.
+
+- [Development and debugging](docs/development.md)
+- [Installation and release](docs/distribution.md)
+- [Architecture](docs/architecture.md) · [Data and naming protocol](docs/protocol.md)
+- [Roadmap](docs/roadmap.md) · [Changelog](CHANGELOG.md)
+
+Not affiliated with or endorsed by OpenAI. No open-source license is currently granted (`UNLICENSED`).

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+<p align="center"><img src="assets/banner.png" alt="Codex Tags — 少翻列表，快速找到会话。" width="100%"></p>
+<p align="center"><a href="README.md">English</a> · <b>简体中文</b></p>
+<p align="center"><a href="#开始使用">开始使用</a> · <a href="#命令">命令</a> · <a href="docs/development.md">本地开发</a> · <a href="docs/architecture.md">架构设计</a></p>
+
+为 Codex 提供本地会话管理增强：按标签整理会话、搜索正文，并让 Agent 按你的分类规则命名。
+
+**macOS · Node.js 22+ · 中英文界面**
+
+> **早期版本** — 自动化检查已通过。全新账户冷启动及手动授权后的首次命名仍需完整端到端验收，详见[验证范围](docs/compatibility.md)。
+
+## 功能
+
+- **融入侧边栏：** 标签筛选、低干扰的标题标签，以及 Tags 会话看板。
+- **本地搜索：** 搜索标题和已索引的用户/助手正文，高亮关键词。
+- **自定义分类：** 默认 Feature、Bug、Design、Research 四类；可自定义颜色和可选分类描述。
+- **Agent 辅助命名：** 使用 `[Tag]标题`，不带日期；首次提交时获得最新分类规则。
+- **三个插件 Skill：** `doctor` 检查健康状态，`initial` 分类已有活跃会话，`rename` 命名当前会话。
+- **中英文界面：** 跟随 Codex 当前语言，不翻译用户自己的标签。
+
+## 开始使用
+
+### 1. 安装 CLI 和插件
+
+先完成正在运行的任务。如果 Codex 已打开但未启用 Tags，请手动退出，再执行：
+
+```bash
+npx @c0sc0s/codex-tags@latest
+```
+
+### 2. 授权 Hook
+
+打开 **Codex → Plugins → Codex Tags**，检查并信任/启用 **SessionStart、UserPromptSubmit、SessionEnd**。
+
+**下次启动：** 使用 `~/Applications/Codex Tags.app`，可拖到 Dock 固定。它启动的是官方 App，不是第二套 Codex；不会自动重启或安装启动守护进程。命名由 Agent 辅助完成，不保证每次确定性改名。
+
+<details>
+<summary>从源码开发或安装</summary>
+
+```bash
+git clone https://github.com/c0sc0s/codex-tags.git
+cd codex-tags
+npm ci
+npm run verify
+node bin/codex-tags.mjs install
+```
+
+随后按上面的步骤授权三个 Hook。
+
+</details>
+
+## 命令
+
+执行 `npx @c0sc0s/codex-tags@latest <命令>`；源码安装：`node bin/codex-tags.mjs <命令>`。
+
+| 命令 | 作用 |
+| --- | --- |
+| `install`、`on`、`enable` | 安装当前调用的包版本并开启全部组件 |
+| `off`、`restore`、`disable` | 停止注入并移除命名插件，保留数据 |
+| `status` / `doctor` | 只读查看状态 / 诊断是否就绪 |
+| `update` | 安装当前调用的版本；使用 `@latest` 才会获取最新版 |
+| `uninstall` | 移除自有组件和索引，保留标签设置 |
+| `uninstall --purge` | 进一步移除标签设置和自有缓存 |
+
+操作命令支持 `--json`。Hook 授权必须由用户在 Codex 中手动确认。
+
+## 隐私与兼容性
+
+CLI 安装本地代码，通过 Codex 插件命令注册插件；**不会**修改官方签名应用、会话记录或登录信息。本地 SQLite 索引只向界面返回有限的命中片段。
+
+注入依赖本机调试端口及 Codex 私有 DOM/数据库结构，不是官方侧边栏扩展 API；Codex 更新后可能需要适配。调试权限较高，请只在可信电脑上使用。详见[验证范围与限制](docs/compatibility.md)。
+
+## 开发
+
+```bash
+npm run dev:apply   # 构建 → 更新安装文件 → 热应用
+npm run verify     # 构建、语法、类型与回归测试
+npm run test:package
+```
+
+快速调试需要 Codex 已激活且带调试端口运行；目前没有 HMR 服务。
+
+- [本地开发与调试](docs/development.md)
+- [安装与发布](docs/distribution.md)
+- [架构](docs/architecture.md) · [数据与命名协议](docs/protocol.md)
+- [后续规划](docs/roadmap.md) · [更新记录](CHANGELOG.md)
+
+本项目独立开发，不隶属于 OpenAI，也未经其背书。目前没有开放源代码许可授权（`UNLICENSED`）。

package/assets/README.md

@@ -0,0 +1,19 @@
+# Project identity
+
+`logo.png` is the shared Codex Tags project mark: a cobalt-blue background with a white dot-and-ring ASCII-style tag. It is independent of OpenAI's branding.
+
+`banner.png` is the wide README masthead shared by both languages. It pairs the project name and tagline with the approved tag artwork; the square App icon remains unchanged. The READMEs include localized alt text and separate language/navigation links.
+
+`icon.icns` is the macOS launcher asset derived from the same image, containing 16, 32, 128, 256 and 512-point representations at 1× and 2×. Convert with macOS `sips` and `iconutil`; do not generate the app and README marks independently.
+
+The final source is the user's explicitly selected image. Preserve it without regenerating or changing the composition. Install updated assets with `node scripts/manage.mjs install`; this does not restart the app.
+
+## Visual direction
+
+A diagonal tag with a punched hole, finely detailed white and pale-blue rings, tonal shading and a cobalt background. Use this same approved artwork across project and launcher surfaces.
+
+## Banner generation
+
+Created with the built-in image generation tool, using `logo.png` as the edit reference. Final prompt:
+
+Use case: compositing. Asset: finished GitHub README hero banner, panoramic 3:1 ratio, 1536x512. Extend the supplied approved cobalt-blue dot-matrix tag artwork into a refined horizontal project masthead. Preserve the tag's fine white rings, diagonal shape, punched hole, brightness and original blue palette faithfully; place it on the RIGHT third, fully visible with comfortable padding, seamless blue background edge-to-edge (no square image tile or seam). LEFT side: precise large white modern sans-serif typography reading exactly 'Codex Tags'. Beneath it, smaller pale-blue text exactly 'Less scrolling. More finding.' Left text aligned with generous margins, vertically centered. Overall composition left 60% quiet typography, right 40% detailed tag art. Restrained editorial technology identity; minimal, polished, crisp readable typography at 800px display width. No additional words, badges, icons, UI, borders, cards, buttons, watermark, textures or decoration. Keep strong contrast and ample negative space. Output one complete banner, not a mockup.

package/bin/codex-tags.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createManager } from "../scripts/manager-core.mjs";
+import { parseCliOptions } from "../scripts/cli-options.mjs";
+import { activationHealth } from "../scripts/health.mjs";
+import { withLifecycleLock } from "../scripts/lifecycle-lock.mjs";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+
+const help = `Codex Tags ${packageJson.version}
+
+Usage: codex-tags [command] [options]
+Without a command, installs and activates Codex Tags.
+
+Commands:
+  install, enable, on   Install every component and turn Codex Tags on
+  disable, off          Turn UI injection and the naming hook off; keep data
+  status                Show runtime, plugin, index, and UI status
+  doctor                Diagnose the complete installation without changing it
+  update                Install this package version and turn it on
+  restore               Alias for disable
+  uninstall             Remove owned files; keep tag settings by default
+
+Options:
+  --json                 Machine-readable output
+  --purge                With uninstall, also remove tag settings
+  -h, --help             Show help
+  -v, --version          Show version
+
+Recommended:
+  npx @c0sc0s/codex-tags@latest install
+  npx @c0sc0s/codex-tags@latest off
+  npx @c0sc0s/codex-tags@latest on
+`;
+
+function print(result) {
+  if (json) return console.log(JSON.stringify(result, null, 2));
+  if (result.status === "enabled") {
+    console.log(`Codex Tags ${result.installation.pluginVersion} is enabled.`);
+    console.log("Use ~/Applications/Codex Tags.app to launch with Tags; add it to your Dock. The official entry does not auto-activate Tags.");
+    console.log("Next: open Codex → Plugins → Codex Tags and trust/enable all three hooks (SessionStart, UserPromptSubmit, SessionEnd).");
+    console.log("New sessions can then use your tags automatically. Existing sessions are unchanged; the optional initial skill organizes them.");
+  } else if (result.status === "incomplete") {
+    console.error("Files were installed, but activation is not ready:");
+    for (const check of result.health.checks.filter(({ ok }) => !ok)) console.error(`  - ${check.message}`);
+    console.error("Run codex-tags doctor for details; rerun install to retry, or off to disable.");
+  } else if (result.status === "disabled") {
+    console.log("Codex Tags is disabled. Tag settings and the local index were preserved.");
+  } else if (result.status === "uninstalled") {
+    console.log(`Codex Tags was uninstalled. Settings preserved: ${result.settingsPreserved ? "yes" : "no"}.`);
+  } else {
+    const health = result.checks ? result : activationHealth(result);
+    console.log(health.ok ? "Tags runtime is ready." : "Tags runtime is not fully active (it may be disabled or Codex may be closed).");
+    for (const check of health.checks) console.log(`${check.ok ? "OK" : "--"} ${check.message}`);
+    console.log("Hook trust is managed in Codex Plugins and must be reviewed there. Use --json for technical details.");
+  }
+}
+
+try {
+  const { command, purge } = parseCliOptions(args);
+  const manager = ["help", "version"].includes(command) ? null : createManager({ packageRoot });
+  const mutate = (operation) => withLifecycleLock(manager.paths.installRoot, operation);
+  if (command === "version") console.log(packageJson.version);
+  else if (command === "help") console.log(help);
+  else if (["install", "enable", "on", "update"].includes(command)) {
+    if (!json) console.error("Installing Codex Tags. If Codex is already open without Tags, quit it first. No automatic restart will occur.");
+    const result = await mutate(() => manager.enable());
+    print(result);
+    if (result.status !== "enabled") process.exitCode = 1;
+  }
+  else if (["disable", "off", "restore"].includes(command)) print(await mutate(() => manager.disable()));
+  else if (command === "status") print(await manager.status());
+  else if (command === "doctor") {
+    const result = await manager.doctor();
+    print(result);
+    if (!result.ok) process.exitCode = 1;
+  } else if (command === "uninstall") print(await mutate(() => manager.uninstall({ purge })));
+  else throw new Error(`Unknown command: ${command}`);
+} catch (error) {
+  if (json) console.error(JSON.stringify({ ok: false, error: error.message }, null, 2));
+  else console.error(`Codex Tags: ${error.message}`);
+  process.exitCode = 1;
+}

package/docs/architecture.md

@@ -0,0 +1,56 @@
+# Architecture
+
+[Development](development.md) · [Protocol](protocol.md) · [Roadmap](roadmap.md)
+
+Codex Tags is a reversible enhancement, not a Codex fork.
+
+## Ownership
+
+| Layer | Owns | Must not own |
+| --- | --- | --- |
+| CLI / manager | Installation, activation, removal, diagnostics | Session naming or UI behavior |
+| Dedicated launcher | Explicitly start the official app with loopback debugging | Monitoring launches or restarting a running app |
+| Controller services | CDP targets, settings, catalog, search index | DOM selectors or UI state |
+| Injected UI | Presentation, interactions, reversible decoration | Filesystem access or durable settings |
+| Host adapter | Codex selectors and native row bindings | Classification policy |
+| Hooks / skills | Live classification guidance for the agent | Direct transcript/title database writes |
+
+## Data flow
+
+```text
+Codex state database ──read-only──▶ SessionCatalog ──metadata──┐
+Codex session JSONL ──read-only──▶ SQLite FTS5 ──snippets──────┤
+                                                            ▼
+settings.json ◀── SettingsRepository ◀── ControllerRouter ⇄ injected UI
+     │                                                      │
+     └── hook / naming skills → Codex agent                  └── host adapter
+```
+
+The active local catalog is independent of sidebar expansion. Remote-only sessions remain best-effort DOM discovery. Schema mismatch reports an incomplete catalog and falls back to visible/cached rows. Conversation text stays in the local index; only bounded matching snippets cross the bridge.
+
+## Resource boundaries
+
+- **SettingsRepository:** normalization, migration, serialized atomic writes. Renderer storage is only a cache; concurrent windows currently use last-writer-wins.
+- **SessionCatalog:** read-only schema-checked metadata, changed snapshots about every 5 seconds. Excludes subagents and internal guardian reviews using `thread_source` and legacy `source` provenance; standalone agent-created tasks remain visible. Filtered snapshots prune cached local entries, keeping counts and search scope consistent.
+- **SessionRegistry:** joins metadata and temporary native bindings using canonical local IDs.
+- **SessionSearchIndex:** incremental FTS5 indexing, with discovery/refresh about every 30 seconds and bounded text extraction.
+- **CodexProcess / TargetRegistry:** process ownership, target discovery, versioned injection and client cleanup.
+- **HostLifecycle:** coalesced native changes and pointer/input-safe refresh.
+- **DashboardView:** modal controls and interaction state; Preact result rows. Background updates preserve IME, menus, drafts and scroll.
+- **ControllerRouter:** validated intent-shaped messages. Navigation requires a UUID present in the current catalog.
+
+## Stack and evolution
+
+Browser: strict TypeScript, Preact result components, bundled Motion, esbuild IIFE. Controller/CLI: Node ESM and better-sqlite3. No remotely loaded runtime scripts.
+
+The dashboard mixes imperative controls and Preact rows. Migrate to a single Preact root when interaction complexity justifies it; do not introduce a general framework solely for uniformity.
+
+## Safety
+
+Native title DOM and listeners have restoration paths. Missing host capabilities should disable the enhancement without damaging native navigation. The signed bundle, session records and authentication data remain untouched.
+
+`Codex Tags.app` explicitly launches the official app with loopback debugging. If a non-debuggable Codex is already open, activation stops with instructions to quit it manually. No launch supervisor is installed; upgrades unload and remove the legacy LaunchAgent. Updates stop old code before replacing files and are retryable, not automatically rolled back.
+
+Private DOM/schema/CDP dependencies cannot be guaranteed across future Codex releases. Keep them at adapter/process/catalog boundaries and verify [compatibility](compatibility.md).
+
+For every new capability, identify its owner, command/message, failure isolation, cleanup and tests. Reuse shared normalization; never add another settings store, selectors outside the adapter, or complete-transcript transfer.

package/docs/compatibility.md

@@ -0,0 +1,47 @@
+# Compatibility policy
+
+Codex Tags integrates with private Codex renderer DOM and therefore cannot promise compatibility with every future Codex build.
+
+Each release must:
+
+- record the tested Codex application version
+- verify required stable `data-*` anchors before mutation
+- disable only the enhancement when an adapter check fails
+- preserve native title content and attributes for exact restoration
+- keep the launcher, compact tag filtering, title rendering, search, IME, menus, scrolling, collapsed groups, and restore path in the real-app smoke matrix
+- expose the detected adapter and last error through `status`
+
+Compatibility failures must never trigger edits to the official application bundle. A failed injection leaves the original sidebar operational.
+
+## Candidate verification — 2026-09-07
+
+- Codex desktop: `26.901.51231` (build `8109`), macOS, bundle identifier `com.openai.codex`.
+- Runtime candidate: `6.0.11`; npm candidate: `@c0sc0s/codex-tags@0.5.0`.
+- Actual tarball installation and repeated source installation both reached healthy state without restarting the already-debuggable app.
+- Live UI checks passed: navigation/dialog, Chinese input composition, local search response, sort menu persistence/contrast, unsaved tag editor retention, and title highlighting.
+- Production dependency audit reported zero known vulnerabilities at verification time.
+- Pending: a clean-account cold launch from the dedicated Tags launcher, manual hook authorization and an actual first-turn naming check. Automated hook contract tests do not replace that permission boundary.
+
+`npm run qa:app` is a content-free, non-restarting smoke against an already injected app. It does not rename sessions or save tag edits. Broader cold-launch and rollback scenarios remain manual release gates.
+
+## Release acceptance matrix
+
+| Scenario | Required result | Status |
+| --- | --- | --- |
+| Source verification | Build, syntax, types and regression tests pass | Passed locally |
+| Packed npm consumer | CLI, standalone native SQLite and three skills load | Passed locally |
+| Already-open app | UI mounts; search, IME, menus and drafts stay stable | Passed locally |
+| Clean-account cold launch | Dedicated launcher activates; running non-debuggable app is left untouched | Pending |
+| Manual hook trust | First new prompt gets current tags; resumed/later prompts do not | Pending real-app check |
+| Never-expanded navigation | Catalog result opens the correct session | Pending real-app check |
+| Lifecycle recovery | off/on/update/restore and both uninstall modes preserve unrelated data | Pending clean-account check |
+| Published npm entry | Exact `npx …@latest` flow succeeds | Pending publication |
+
+## Known limits
+
+- macOS only; no verified Windows/Linux installer.
+- The catalog uses a private, schema-checked local database. Remote-only sessions are best-effort sidebar discovery.
+- Text extraction supports local user/assistant message records, caps fields at 24,000 characters and sessions at 500,000, and excludes tool output. Search returns at most 100 unique sessions; it is not exhaustive transcript export.
+- A newer extractor rebuilds the owned search cache; original session files are unchanged.
+- Multi-window settings use last-writer-wins. Updates are retryable but do not yet offer transactional rollback.
+- Future Codex builds require renewed adapter and lifecycle checks. Hook trust cannot be granted or certified by doctor.

package/docs/development.md

@@ -0,0 +1,84 @@
+# Development and debugging
+
+[English home](../README.md) · [中文首页](../README.zh-CN.md)
+
+## Setup
+
+Use macOS, Node.js 22+, and the official Codex desktop app. The installer verifies its bundle identity, not just its filename.
+
+```bash
+git clone https://github.com/c0sc0s/codex-tags.git
+cd codex-tags
+npm ci
+npm run verify
+node bin/codex-tags.mjs install
+```
+
+Activation never restarts a running Codex. If the app is open without debugging, ask the user to quit it before launching `~/Applications/Codex Tags.app`. Review the three hooks in Codex Plugins separately.
+
+Edit this checkout, never installed files in Application Support or the plugin cache.
+
+## Edit → preview
+
+```bash
+npm run dev:apply
+```
+
+This runs build → repository `install` → `apply` against an already debug-enabled app. No watcher/HMR is provided. Unlike public CLI installation, repository `node scripts/manage.mjs install` only refreshes files and the dedicated launcher and removes the legacy supervisor; it does not register/enable the plugin or activate the UI.
+
+- Browser changes: bump `RUNTIME_VERSION` in `runtime/src/inject-expression.mjs`, then build/install/apply.
+- Controller changes: install/apply so the controller uses the updated installed modules.
+- Hook/skill changes: refresh the plugin cachebuster and use the public installer; renewed hook review may be required.
+- Never edit `runtime/dist/injected.js` manually; commit the generated bundle with source changes.
+
+## Code map
+
+| Concern | Owner |
+| --- | --- |
+| CLI and installation | `bin/codex-tags.mjs`, `scripts/{cli-options,manager-core}.mjs` |
+| Readiness / mutation lock | `scripts/{health,lifecycle-lock}.mjs` |
+| App lifecycle / CDP | `runtime/src/{codex-process,cdp-client,runtime-target-registry}.mjs` |
+| Controller / bridge | `runtime/src/{controller,controller-router,protocol}.mjs` |
+| Catalog / search | `runtime/src/{session-catalog,content-index,search-index}.mjs` |
+| Saved definitions | `runtime/src/{settings-repository,tag-settings}.mjs` |
+| Host selectors | `runtime/src/injected/codex-dom-adapter.ts` |
+| UI lifecycle | `runtime/src/injected/{runtime,host-lifecycle}.ts` |
+| Dashboard / sidebar | `runtime/src/injected/dashboard-view.ts`, `components/`, `sidebar-tag-filter.ts`, `title-decorator.ts` |
+| UI data / language | `runtime/src/injected/{session-registry,search,store,i18n}.ts` |
+| Naming / skills | `hooks/session-naming.mjs`, `skills/{doctor,initial,rename}/` |
+
+## Verification
+
+```bash
+npm run verify
+npm run test:package
+npm run dev:apply
+node bin/codex-tags.mjs doctor
+npm run qa:app
+git diff --check
+```
+
+The package smoke installs the actual tarball into a temporary consumer and checks hoisted dependencies, standalone SQLite, CLI validation and plugin payload without changing real Codex data.
+
+App QA requires an already injected app. It checks IME, search, menu persistence/contrast, draft retention, highlighting and cleanup without restarting, renaming tasks or saving tag edits. Cold launch, trusted first-turn naming and uninstall/restore remain separate [release checks](compatibility.md).
+
+## Debugging
+
+Start with `node bin/codex-tags.mjs doctor --json`.
+
+Logs under `~/Library/Application Support/Codex Sidebar Tags/`: `controller.log`, `launcher.log`. Installation metadata is in `install.json`. Never share credentials or conversation text in diagnostics.
+
+Renderer diagnostics: `window.__codexSidebarTags.status()`, `debug()`, `dispose()`.
+
+| Symptom | Check |
+| --- | --- |
+| Missing UI | Owned CDP, source/active versions, sidebar mount |
+| Port 9341 conflict | Report it; never kill a foreign process |
+| Stale UI | Build → install → apply; runtime version bump |
+| Missing body match | Index status, supported record shapes, text limits and refresh delay |
+| Codex update regression | Host adapter / catalog schema; never patch the signed app |
+| Stale CLI lock | Confirm no Tags CLI is running, then remove only the named lock |
+
+Testing overrides: `CODEX_TAGS_INSTALL_DIR` (runtime), `CODEX_TAGS_APPLICATIONS_DIR` (launcher), `CODEX_TAGS_CDP_PORT` (default 9341), `CODEX_HOME` (Codex data), `CODEX_TAGS_SETTINGS_PATH` (hook settings), `CODEX_TAGS_STATE_DIR` (hook markers). They do not isolate every macOS/plugin side effect; unit tests use injected fake process runners.
+
+Use `node bin/codex-tags.mjs off` to disable all components while keeping settings. Uninstall only with explicit user permission.