holo-codex 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "codex-auto-pr-loop",
+  "interface": {
+    "displayName": "HOLO-Codex"
+  },
+  "plugins": [
+    {
+      "name": "autonomous-pr-loop",
+      "source": {
+        "source": "local",
+        "path": "./plugins/autonomous-pr-loop"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Engineering"
+    }
+  ]
+}

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Thanks for helping improve HOLO-Codex.
+
+## Development Setup
+
+```bash
+pnpm install
+pnpm build:hooks
+pnpm test
+pnpm lint
+```
+
+Use `pnpm agent-loop ...` while working inside this repository. Use the global `agent-loop ...` command only after running the local install workflow described in [Local Release Readiness](./docs/local-release-readiness.md).
+
+## Runtime Compatibility Names
+
+HOLO-Codex is the public product name. The `agent-loop` CLI, `.agent-loop/` runtime directory, `autonomous-pr-loop` plugin id, and `plugins/autonomous-pr-loop/` source path are stable compatibility identifiers. Do not rename them without a migration plan.
+
+## PR Workflow
+
+- Keep each PR scoped to one issue.
+- Start from latest `main`.
+- Do not commit `.agent-loop/`, SQLite files, tokens, raw hook payloads, raw transcripts, or worker logs.
+- Run focused tests for touched areas, then `pnpm lint` and `pnpm test`.
+- If GitNexus is configured, inspect impact before risky symbol edits and run detect before committing:
+
+Use the GitNexus repo id configured on your machine:
+
+```bash
+npx gitnexus detect-changes --repo <indexed-repo-id> --scope staged
+```
+
+## Maintainer Delivery Loop
+
+For repository self-maintenance, use the local delivery workflow:
+
+```bash
+pnpm agent-loop delivery bind --issue ISSUE --title "..." --url https://github.com/OWNER/REPO/issues/ISSUE --json
+pnpm agent-loop delivery stage --stage plan --status active --summary "Planning work." --json
+```
+
+Record meaningful stage evidence for plan, build, verify, PR, review, merge readiness, and cleanup. PR bodies and reviewer comments should include the bound run id when using the delivery loop.
+
+## Review Expectations
+
+- Classify findings as P0/P1/P2/P3.
+- Fix real P0/P1/P2 findings before merge unless a P2 is explicitly routed to a linked follow-up issue.
+- Keep P3 polish in the same PR when it is small and in scope.
+- Reviewer reports from external agents should be posted as PR comments when that workflow is used.
+
+## Public Source Hygiene
+
+Historical private planning docs, local handoff notes, Logseq artifacts, and runtime files should not be included in public release artifacts. The public repository should be usable from active docs, not from private chat history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HOLO-Codex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# HOLO-Codex
+
+[中文文档](./README.zh-CN.md)
+
+![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
+
+HOLO-Codex, short for **Human On Loop Codex**, turns long-running Codex workflows into observable, recoverable, human-on-loop systems. The operator sets goals and boundaries, observes progress, and steps in only when a real gate needs attention.
+
+The supervisor owns durable workflow state, evidence, gates, worker orchestration, Codex hooks, the MCP control plane, and the local dashboard. Workers perform scoped tasks and return structured output.
+
+## What It Provides
+
+- A Codex plugin under `plugins/autonomous-pr-loop/`.
+- The `agent-loop` CLI for local loop state, hooks, dashboard, workflow evidence, and rollback-safe local install.
+- Local SQLite state under `.agent-loop/`.
+- A local dashboard for Mission Control, workflow board, observability, gates, review/CI state, workers, artifacts, recovery, notifications, policy config, and theme modes.
+- stdio MCP control plane.
+- Codex hooks for policy checks and observability.
+- TypeScript + Vitest test suite.
+- Bilingual display support for `zh-CN`, `en-US`, and `system` locale selection.
+- Workflow profiles, role profiles, `generic-loop`, and the first bundled workflow: `pr-loop`.
+
+This is not a hosted service. It does not run GitHub webhooks or cloud workers.
+
+## Compatibility Names
+
+HOLO-Codex is the public product name. Some stable runtime identifiers intentionally keep their legacy names for compatibility:
+
+- CLI command: `agent-loop`
+- Runtime state directory: `.agent-loop/`
+- Plugin id and MCP server id: `autonomous-pr-loop`
+- Source directory: `plugins/autonomous-pr-loop/`
+- npm package name: `holo-codex`
+- Local marketplace entry name: `codex-auto-pr-loop`
+
+Do not treat those names as a second product. They are compatibility identifiers.
+
+## First Workflow: PR Delivery
+
+PR delivery is the first complete workflow shipped with HOLO-Codex. It is the strongest sample of the loop model, not the product boundary.
+
+Typical flow:
+
+```text
+sync main
+bind work item
+plan
+build
+verify
+open PR
+run review / CI
+fix findings
+check merge readiness
+merge
+cleanup
+```
+
+The dashboard and MCP tools read persisted loop state. They do not rely on chat history.
+
+The same control-plane model can support other long-running Codex workflows such as release preparation, repo hygiene, security review, docs publishing, migrations, evaluations, and customer-issue triage.
+
+## Install
+
+Canonical public source:
+
+```text
+https://github.com/tizerluo/HOLO-Codex
+```
+
+Requirements:
+
+- Node.js `>=22.5`
+- `git`
+- GitHub CLI `gh`
+- Codex CLI / plugin support
+- `pnpm` when installing from source or using rollback-snapshot local install
+- Optional but recommended: GitNexus via `npx gitnexus`
+
+Install from npm:
+
+```bash
+npm install --global holo-codex
+# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo doctor
+```
+
+The npm package installs the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target binding without reinstalling the global CLI. To remove an npm install, run `agent-loop hooks unbind --repo /path/to/repo`, remove HOLO-Codex router entries from `~/.codex/hooks.json` only when no target repositories still use them, and then run `npm uninstall --global holo-codex`.
+
+Install from source when developing HOLO-Codex or when you want to inspect the source checkout directly:
+
+```bash
+git clone https://github.com/tizerluo/HOLO-Codex.git
+cd HOLO-Codex
+pnpm install
+pnpm build:hooks
+# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
+pnpm agent-loop local install --repo /path/to/repo
+agent-loop --repo /path/to/repo status
+```
+
+`pnpm agent-loop ...` is the source checkout command. `agent-loop ...` is the global convenience command for day-to-day use from any directory after npm or local source install. Use `agent-loop local snapshots prune --keep 10` to preview old snapshot cleanup, and add `--apply` only when you want to delete valid old snapshots.
+
+For a complete local install, upgrade, reinstall, uninstall, and smoke-test checklist, see [Local Release Readiness](./docs/local-release-readiness.md).
+
+Add HOLO-Codex to the local Codex plugin marketplace. For npm installs:
+
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
+
+For source installs:
+
+```bash
+codex plugin marketplace add /path/to/HOLO-Codex
+```
+
+Then enable the `autonomous-pr-loop` plugin in Codex. Plugin enablement and global CLI installation are separate steps.
+
+## Initialize State
+
+Run from the target repository root:
+
+```bash
+agent-loop --repo /path/to/repo init
+agent-loop --repo /path/to/repo doctor
+agent-loop --repo /path/to/repo status
+```
+
+Install Codex hooks:
+
+```bash
+agent-loop install-hooks --repo /path/to/repo
+```
+
+This installs one stable hook router into `~/.codex/hooks.json`, preserves existing user hooks, and records the target repository binding under `~/.codex/agent-loop/hook-bindings.json`.
+
+Multi-repo note: multiple repositories can share the same `CODEX_HOME`; hook events are routed by Codex cwd/worktree/session context before any repo state is written or policy is applied. A separate `CODEX_HOME` remains useful for high-isolation sandbox testing.
+
+Runtime files are written to `.agent-loop/` and must not be committed.
+
+## Dashboard
+
+```bash
+agent-loop --repo /path/to/repo dashboard
+```
+
+The command prints a loopback URL on stdout and a fallback session token on stderr:
+
+```text
+dashboard started
+url: http://127.0.0.1:<port>/
+targetRepoRoot: /path/to/repo
+```
+
+Dashboard mutations require the local session token and go through the shared controller. The UI does not write SQLite directly. Loopback dashboard sessions unlock through a same-origin session bootstrap; the stderr token is only a fallback for static UI or recovery. Do not copy it into docs, logs, PR bodies, commits, artifacts, or screenshots.
+
+Dashboard-visible delivery work is produced by persisted `agent-loop` actions and workflow evidence. Direct terminal edits or commander decisions are not automatically visible unless they are recorded through agent-loop events, artifacts, or PR comments. For the current self-maintenance flow, see [Self-bootstrap workflow](./docs/self-bootstrap.md). For an end-to-end audit template, see [Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md).
+
+## Common CLI
+
+```bash
+agent-loop --repo /path/to/repo status
+agent-loop --repo /path/to/repo init --dry-run
+agent-loop --repo /path/to/repo doctor
+agent-loop --repo /path/to/repo run --dry-run
+agent-loop --repo /path/to/repo run --until=gate
+agent-loop --repo /path/to/repo step
+agent-loop --repo /path/to/repo resume
+agent-loop --repo /path/to/repo stop
+agent-loop --repo /path/to/repo timeline --limit 20
+agent-loop --repo /path/to/repo workers --events
+agent-loop --repo /path/to/repo observe
+agent-loop --repo /path/to/repo audit-export --run RUN_ID --format markdown
+agent-loop --repo /path/to/repo recover
+agent-loop --repo /path/to/repo approve-gate <gate-id> --note "reason"
+agent-loop --repo /path/to/repo dashboard
+```
+
+Human-readable CLI output supports `--locale zh-CN|en-US|system`. JSON output remains structured and stable.
+
+## Workflow Profiles And Themes
+
+The default workflow remains `pr-loop` with `default_pr_loop` and `default_pr_roles`. Policy Config can also select `generic-loop` with built-in profiles for research reports, document preparation, repo hygiene, weekly review, and data extraction workflows. For a concrete non-PR workflow, see the [generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md).
+
+Dashboard theme is a local browser preference. It supports `light`, `dark`, and `system`, and does not write to repo config or SQLite.
+
+## Safety Boundaries
+
+- Workers may edit files but cannot commit, push, create PRs, mark PRs ready, or merge.
+- The supervisor owns Git and GitHub lifecycle actions.
+- Destructive Git/GitHub commands are blocked by command policy and hooks.
+- Merge readiness depends on config, review/CI evidence, open review comments, scope guard, and policy decisions.
+- Never store secrets in code, docs, logs, artifacts, commits, or PR bodies.
+- Hooks cover the Codex tool loop, not manual commands run in an external terminal.
+
+## Development
+
+```bash
+pnpm test
+pnpm lint
+```
+
+More docs:
+
+- [Install](./docs/install.md)
+- [Local Release Readiness](./docs/local-release-readiness.md)
+- [Source Release Checklist](./docs/release-checklist.md)
+- [Self-bootstrap workflow](./docs/self-bootstrap.md)
+- [Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md)
+- [Generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md)
+- [Trust and Safety](./docs/trust-and-safety.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)

package/README.zh-CN.md

@@ -0,0 +1,215 @@
+# HOLO-Codex
+
+[English README](./README.md)
+
+![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
+
+HOLO-Codex 是 **Human On Loop Codex** 的缩写，它把长流程 Codex workflow 变成可观察、可恢复、可人工接管的 loop。人设定目标和边界、观察进展，并只在真实 gate 需要关注时回到环上。
+
+Supervisor 负责持久化 workflow 状态、evidence、gates、worker 编排、Codex hooks、MCP control plane 和本地 dashboard。Worker 只做受控任务并返回结构化输出。
+
+## 提供能力
+
+- `plugins/autonomous-pr-loop/` 下的 Codex 插件。
+- `agent-loop` CLI：管理本地 loop 状态、hooks、dashboard、workflow evidence 和可回滚本地安装。
+- `.agent-loop/` 下的本地 SQLite 状态。
+- 本地 dashboard：Mission Control、workflow board、Observability Console、Gate、Review/CI、Worker、Artifact、Notifications、Recovery、Policy Config、主题模式。
+- stdio MCP control plane。
+- 用于 policy 检查和 observability 的 Codex hooks。
+- TypeScript + Vitest 测试套件。
+- `zh-CN`、`en-US`、`system` 双语显示支持。
+- workflow profile、role profile、`generic-loop`，以及第一个内置 workflow：`pr-loop`。
+
+这不是托管服务，不提供 GitHub webhook daemon 或云端 worker。
+
+## 兼容名称
+
+HOLO-Codex 是公开产品名。一些稳定运行时标识会继续保留旧名称，以避免破坏已有安装和本地状态：
+
+- CLI 命令：`agent-loop`
+- 运行态目录：`.agent-loop/`
+- Plugin id 和 MCP server id：`autonomous-pr-loop`
+- 源码目录：`plugins/autonomous-pr-loop/`
+- npm package 名：`holo-codex`
+- 本地 marketplace 条目名：`codex-auto-pr-loop`
+
+这些是兼容标识，不是第二个产品名。
+
+## 第一个工作流：PR 交付
+
+PR 交付是 HOLO-Codex 随附的第一个完整 workflow，也是 loop 模型最强的样板，但不是产品边界。
+
+典型流程：
+
+```text
+sync main
+bind work item
+plan
+build
+verify
+open PR
+run review / CI
+fix findings
+check merge readiness
+merge
+cleanup
+```
+
+Dashboard 和 MCP tools 读取持久化 loop 状态，不依赖聊天历史。
+
+同一套 control plane 也可以承载其他长流程 Codex workflow，例如 release 准备、仓库卫生审计、安全审查、文档发布、迁移、评测和客户 issue 分诊。
+
+## 安装
+
+公开源码入口：
+
+```text
+https://github.com/tizerluo/HOLO-Codex
+```
+
+依赖：
+
+- Node.js `>=22.5`
+- `git`
+- GitHub CLI `gh`
+- Codex CLI / plugin support
+- 从源码安装或使用 snapshot/rollback local install 时需要 `pnpm`
+- 可选但推荐：GitNexus，使用 `npx gitnexus`
+
+从 npm 安装：
+
+```bash
+npm install --global holo-codex
+# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo doctor
+```
+
+npm package 会安装 `agent-loop` CLI。`agent-loop install-hooks` 会安装或刷新 hook router 和目标仓库绑定，不会重新安装全局 CLI。移除 npm 安装时，先运行 `agent-loop hooks unbind --repo /path/to/repo`；确认没有任何目标仓库还在使用 HOLO-Codex router 后，再从 `~/.codex/hooks.json` 手动移除 HOLO-Codex router entries，最后运行 `npm uninstall --global holo-codex`。
+
+开发 HOLO-Codex 或需要直接检查源码 checkout 时，从源码安装：
+
+```bash
+git clone https://github.com/tizerluo/HOLO-Codex.git
+cd HOLO-Codex
+pnpm install
+pnpm build:hooks
+# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
+pnpm agent-loop local install --repo /path/to/repo
+agent-loop --repo /path/to/repo status
+```
+
+`pnpm agent-loop ...` 是源码 checkout 内的命令。`agent-loop ...` 是 npm 或本地源码安装后从任意目录日常使用的全局命令。用 `agent-loop local snapshots prune --keep 10` 预览旧 snapshot 清理；确认要删除时再加 `--apply`。
+
+完整的本地安装、升级、重装、卸载和 smoke test 清单见：[Local Release Readiness](./docs/local-release-readiness.md)。
+
+把 HOLO-Codex 加入本地 Codex plugin marketplace。npm 安装时：
+
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
+
+源码安装时：
+
+```bash
+codex plugin marketplace add /path/to/HOLO-Codex
+```
+
+然后在 Codex 中启用 `autonomous-pr-loop` 插件。Codex plugin 启用和全局 CLI 安装是两件事。
+
+## 初始化状态
+
+在目标仓库根目录执行：
+
+```bash
+agent-loop --repo /path/to/repo init
+agent-loop --repo /path/to/repo doctor
+agent-loop --repo /path/to/repo status
+```
+
+安装 Codex hooks：
+
+```bash
+agent-loop install-hooks --repo /path/to/repo
+```
+
+这会向 `~/.codex/hooks.json` 安装一组稳定 hook router，保留已有用户 hooks，并在 `~/.codex/agent-loop/hook-bindings.json` 记录目标仓库绑定。
+
+多仓库注意：多个仓库可以共用同一个 `CODEX_HOME`；hook event 会先按 Codex cwd/worktree/session context 路由，再写入仓库状态或执行 policy。独立 `CODEX_HOME` 仍适合高隔离 sandbox 测试。
+
+运行态文件写入 `.agent-loop/`，不要提交。
+
+## Dashboard
+
+```bash
+agent-loop --repo /path/to/repo dashboard
+```
+
+命令会在 stdout 打印 loopback URL，并在 stderr 单独打印 fallback session token：
+
+```text
+dashboard 已启动
+url: http://127.0.0.1:<port>/
+targetRepoRoot: /path/to/repo
+```
+
+Dashboard mutation 必须带本地 session token，并统一走 controller。UI 不直接写 SQLite。本地 loopback dashboard 会用同源 session bootstrap 自动解锁。stderr token 只作为静态 UI 或恢复场景的 fallback；不要把它复制到 docs、日志、PR body、commit、artifact 或截图里。
+
+Dashboard 能看到的交付工作来自持久化的 `agent-loop` 动作和 workflow evidence。直接在终端改文件或 commander 决策不会自动出现在 dashboard，除非它们被记录成 agent-loop event、artifact 或 PR comment。当前自维护流程见：[自举维护流程](./docs/self-bootstrap.md)。端到端审计模板见：[Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md)。
+
+## 常用 CLI
+
+```bash
+agent-loop --repo /path/to/repo status
+agent-loop --repo /path/to/repo init --dry-run
+agent-loop --repo /path/to/repo doctor
+agent-loop --repo /path/to/repo run --dry-run
+agent-loop --repo /path/to/repo run --until=gate
+agent-loop --repo /path/to/repo step
+agent-loop --repo /path/to/repo resume
+agent-loop --repo /path/to/repo stop
+agent-loop --repo /path/to/repo timeline --limit 20
+agent-loop --repo /path/to/repo workers --events
+agent-loop --repo /path/to/repo observe
+agent-loop --repo /path/to/repo audit-export --run RUN_ID --format markdown
+agent-loop --repo /path/to/repo recover
+agent-loop --repo /path/to/repo approve-gate <gate-id> --note "reason"
+agent-loop --repo /path/to/repo dashboard
+```
+
+人类可读 CLI 输出支持 `--locale zh-CN|en-US|system`。JSON 输出保持结构化和稳定。
+
+## Workflow Profiles 和主题
+
+默认 workflow 仍是 `pr-loop`，使用 `default_pr_loop` 和 `default_pr_roles`。Policy Config 也可以选择 `generic-loop`，并使用内置的调研报告、文档准备、仓库卫生审计、周报、数据抽取 workflow profiles。具体非 PR 工作流可参考：[generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)。
+
+Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark`、`system`，不会写入 repo config 或 SQLite。
+
+## 安全边界
+
+- Worker 可以改文件，但不能 commit、push、create PR、mark PR ready 或 merge。
+- Supervisor 负责 Git 和 GitHub 生命周期。
+- 破坏性 Git/GitHub 命令由 command policy 和 hooks 阻止。
+- Merge readiness 由 config、review/CI evidence、open review comments、scope guard 和 policy decisions 共同决定。
+- 不要把密钥写入代码、文档、日志、artifacts、commit 或 PR body。
+- Hooks 只覆盖 Codex tool loop，不拦截外部 Terminal 手动命令。
+
+## 开发
+
+```bash
+pnpm test
+pnpm lint
+```
+
+更多文档：
+
+- [安装](./docs/install.md)
+- [Local Release Readiness](./docs/local-release-readiness.md)
+- [Source Release Checklist](./docs/release-checklist.md)
+- [自举维护流程](./docs/self-bootstrap.md)
+- [Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md)
+- [generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)
+- [信任与安全](./docs/trust-and-safety.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [安全政策](./SECURITY.md)

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+HOLO-Codex is a local-first Codex plugin. It stores runtime state on the user's machine and does not run a hosted service.
+
+## Report A Vulnerability
+
+Please report security issues privately to the repository owner before opening a public issue. Include the affected version or commit, a minimal reproduction, and the expected impact.
+
+Do not include secrets, dashboard tokens, raw hook payloads, raw transcripts, private prompts, or full worker logs in public reports.
+
+## Sensitive Local Data
+
+Never commit or publish:
+
+- `.agent-loop/`
+- SQLite state files, WAL/SHM files, or local databases
+- dashboard session tokens
+- MCP tokens or API keys
+- raw hook payloads
+- raw transcript paths or transcript contents
+- raw worker JSONL logs
+- private prompts or private PR review output
+
+Use the operating system keychain or your configured secret manager for credentials.
+
+## Hook And Dashboard Boundaries
+
+Codex hooks cover Codex tool-loop events only. They do not intercept commands run manually in an external terminal.
+
+Dashboard mutations require the local session token and loopback/origin guards. The dashboard URL should not contain the token; the fallback token printed by `agent-loop dashboard` is for local recovery only.
+
+## Public Release Checklist
+
+Before publishing a public source snapshot or package:
+
+- Run tests and lint.
+- Run a secret/local-state scan.
+- Verify `npm pack --dry-run --json` or the chosen release artifact.
+- Confirm no `.agent-loop` runtime files, dashboard tokens, raw logs, or private handoff documents are included.

package/assets/brand/README.md

@@ -0,0 +1,35 @@
+# HOLO-Codex Brand Assets
+
+This folder contains early deterministic SVG drafts for the HOLO-Codex identity.
+
+## Concept
+
+The mark combines:
+
+- `>_` as the Codex / CLI execution cue.
+- A near-complete loop as the human-on-loop control boundary.
+- An amber intervention dot as the human gate, approval, or pause point.
+
+## Files
+
+- `holo-codex-mark.svg` — transparent standalone mark.
+- `holo-codex-icon.svg` — rounded-square app/plugin icon draft.
+- `holo-codex-lockup.svg` — mark plus wordmark and full-name descriptor.
+- `holo-codex-wordmark-options.svg` — wordmark treatment comparison.
+- `holo-codex-social-preview.svg` — 1280x640 GitHub social preview source.
+- `holo-codex-social-preview.png` — GitHub-uploadable social preview export.
+- `holo-codex-readme-hero.svg` — wide README hero banner draft.
+- `holo-codex-plugin-card.svg` — compact plugin marketplace card draft.
+
+## Draft Palette
+
+- Ink: `#111827`
+- Supporting text: `#475569`
+- Human gate amber: `#f59e0b`
+- Icon surface: `#f8fafc`
+
+## Notes
+
+These are source-hygiene friendly SVG drafts, not final trademark-cleared production identity files. Keep the runtime compatibility names (`agent-loop`, `.agent-loop`, `autonomous-pr-loop`) unchanged unless a migration plan exists.
+
+The current wordmark references the restrained Codex product feel without copying an official OpenAI or Codex wordmark. If a final font is selected, convert the wordmark to outlines before publishing release assets that require exact rendering.

package/assets/brand/holo-codex-icon.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">HOLO-Codex app icon</title>
+  <desc id="desc">A compact HOLO-Codex icon for plugin, app, and favicon use.</desc>
+  <rect x="8" y="8" width="112" height="112" rx="28" fill="#f8fafc" />
+  <path
+    d="M111.3 52.6A49 49 0 1 1 84 19.2"
+    fill="none"
+    stroke="#111827"
+    stroke-width="8"
+    stroke-linecap="round"
+  />
+  <circle cx="98.6" cy="29.4" r="6.5" fill="#f59e0b" />
+  <path
+    d="M41 48L62 64L41 80"
+    fill="none"
+    stroke="#111827"
+    stroke-width="8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <path
+    d="M70 81H91"
+    fill="none"
+    stroke="#111827"
+    stroke-width="8"
+    stroke-linecap="round"
+  />
+</svg>

package/assets/brand/holo-codex-lockup.svg

@@ -0,0 +1,49 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 560 160" role="img" aria-labelledby="title desc">
+  <title id="title">HOLO-Codex lockup</title>
+  <desc id="desc">HOLO-Codex wordmark with terminal prompt loop mark.</desc>
+  <g transform="translate(20 16)">
+    <path
+      d="M111.3 52.6A49 49 0 1 1 84 19.2"
+      fill="none"
+      stroke="#111827"
+      stroke-width="8"
+      stroke-linecap="round"
+    />
+    <circle cx="98.6" cy="29.4" r="6.5" fill="#f59e0b" />
+    <path
+      d="M41 48L62 64L41 80"
+      fill="none"
+      stroke="#111827"
+      stroke-width="8"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    />
+    <path
+      d="M70 81H91"
+      fill="none"
+      stroke="#111827"
+      stroke-width="8"
+      stroke-linecap="round"
+    />
+  </g>
+  <g transform="translate(170 47)">
+    <text
+      x="0"
+      y="42"
+      fill="#111827"
+      font-family="'SF Pro Display', 'OpenAI Sans', Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+      font-size="47"
+      letter-spacing="-0.2"
+    >
+      <tspan font-weight="740">HOLO</tspan><tspan font-weight="570">_Codex</tspan>
+    </text>
+    <text
+      x="2"
+      y="78"
+      fill="#475569"
+      font-family="'SF Pro Text', 'OpenAI Sans', Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+      font-size="18"
+      letter-spacing="-0.1"
+    >Human On Loop Codex</text>
+  </g>
+</svg>