Documentation index¶
English · 简体中文
These guides describe the source revision containing them, not necessarily the last release tag. See the main README and Unreleased changes.
Start with the reasoning-first workflow¶
New user: start with Install & update. Choose either the packaged quick route or the fully supported source/developer route; both converge on reasonfirst setup. Use First-time setup when you need the detailed/manual operator procedure or legacy lifecycle background.
Primary product loop: normal ChatGPT reads and reasons over repository/MR/CI evidence, defines the task and acceptance criteria, ReasonFirst hands the approved task to a coding worker, and bounded implementation/CI evidence returns to ChatGPT + human review. Use the CLI quickstart as the execution-engine/operator reference inside that loop. Direct CLI-only use remains useful for testing, recovery and automation, but is secondary. The optional Bridge Preview is a more privileged orchestration surface; read Architecture before enabling it. Already connected: use daily start/status/stop/restart. Advanced/manual/Windows: use the manual guide and Windows procedure.
Current entry points¶
| Topic | English | 简体中文 |
|---|---|---|
| Install/update: packaged or source route | Install & update | 安装与更新 |
| Detailed/manual first-time setup and first prompt | Operator setup | 详细首次接入 |
| Product and supported capabilities | ReasonFirst | 项目说明 |
| Start the required service and manage its lifecycle | Tunnel lifecycle | 隧道生命周期 |
| Before using a newly proposed GitLab project | Access preflight and user grants | 项目预检与用户授权 |
| Rehearse ChatGPT, Codex and three rounds of one MR | Practice lab | 实战演练 |
| Run the full chat-only managed-worker → MR → matching-head CI loop | Chat-only E2E | 全聊天 E2E |
| Interface responsibilities and evidence | Workflow | 工作流程 |
| Execution-engine setup and controlled implementation | CLI quickstart | 快速上手 |
| Manual/advanced startup, credential alternatives | Operator guide | 手工接入/Windows |
| Manual approved-task handoff and result evidence | Writing template, not a runtime API | 人工交接与证据模板 |
| Current architecture and trust boundaries | Architecture | 架构说明 |
| Architectural intent / rationale | Design philosophy | 设计理念 |
| HTTP-to-HTTPS migration | Migration | 迁移指南 |
| API/MCP private CA, redirects and native Git boundaries | Runtime TLS | 运行时 TLS |
| PR checkout, tests and source updates | Local PR review | 本地 PR 审阅 |
| Diagnosis without weakening controls | Troubleshooting | 分层故障排查 |
| Contribution process | Contributing | 贡献指南 |
| Security reporting and limitations | Security policy | 安全策略 |
| v0.5.0 release notes | 0.5.0 release notes | 0.5.0 中文 release notes |
| Before a public release | Maintainer checklist | 公开发布清单 |
Required before the first ChatGPT prompt¶
Complete prerequisites, start the selected tunnel/MCP, keep its Terminal running, check local readiness, and select the actual app in the normal ChatGPT composer. Then call gitlab_whoami, check_project_access and read files at resolved_commit_sha. Local health, identity alone, or the name of a connector in a message is not end-to-end project-read acceptance.
Keychain is the recommended runtime-key source in the Mac guide, not a mandatory component for every platform. The OpenAI tunnel key, tunnel ID, GitLab token, local allowlist and coding-agent login are different things. Platform tunnel permissions, ChatGPT workspace permissions and GitLab/local project grants are also separate. The first-time guide identifies the responsible user/admin at each stop point. Never assume an earlier shell export survived a new Terminal.
New-project access gate¶
A project name/local folder is not evidence of a remote repository or authorization. On a newly introduced project, call check_project_access before bulk reads or a handoff. On ok: false, show the diagnostic and wait for the user/operator. A 404 or empty filtered listing cannot distinguish absent from inaccessible.
Per-project authorization is GITLAB_ALLOWED_PROJECTS in the local MCP configuration, not OpenAI tunnel settings. Only after explicit approval, append the intended exact project while preserving existing entries, then restart the existing MCP. The helper never creates projects or grants access. This also applies before following older first-task examples.
One reasoning interface, not another required chatbot¶
Normal ChatGPT is the reasoning/review interface. The read-only GitLab Tunnel/MCP supplies repository/MR/CI reads; ActualCoder implements approved local work with codex-cli, copilot-cli, or codex-desktop. The optional Bridge Preview is a separate, more privileged local orchestration surface and should not be confused with the read-only connector. The localhost Assistant, Codex tunnel plugin and Inspector are not prerequisites or acceptance gates. Overview/Logs are optional diagnostics. Not using the Assistant does not disable an upstream bundled helper or uninstall Codex.
The standard GitLab read connector still has no local task-execution role. The optional Bridge Preview exposes local orchestration tools, approvals, finish preview and configured SSH operations. Persistent core TaskSpec/attempt records and bounded EvidencePack are now on main and form the durable boundary between reasoning intent and worker evidence. A successful read does not prove Git push, model login or full application CI works; test those during an approved implementation.
Translation scope and maintenance¶
Keep English and Chinese current guides together, including executable examples, stop conditions, permissions and evidence limits. The new first-time pair records its source baseline and provider-check date; tests check command parity and safe bootstrap behavior. Existing paired quickstart, lifecycle, access, migration and TLS guides remain their topic references.
Historical notes/CHANGELOG are records, and LICENSE is unchanged. Documentation does not create a release, alter permissions, or claim unsupported features. Provider UI/availability can change; consult the primary references linked from the first-time/manual guides.
Historical designs and detailed legacy recipes¶
Old Chinese onboarding and old Chinese setup tutorial are historical, not the required checklist. Do not execute old token-bearing examples, overwrite a working .env, or install optional components merely because a legacy page mentions them.
V0.2 design, V0.2 Codex guide, CodingAgent compatibility guide, V0.3 roadmap and V0.3 audit provide historical context.
Historical focused implementation notes cover publication safety, exit status, history scanning and log evidence. Their filenames record development increments, not the current release state. Persistent TaskSpec/attempt records and the bounded EvidencePack are implemented in v0.5.0; Issue #6 remains the historical/roadmap umbrella, while Issue #10 tracks remaining native-Git trust/destination-policy work.
Chat-only rehearsal¶
- Fully chat-based E2E practice: one normal ChatGPT conversation from live repo read → Bridge-managed edit → reviewed snapshot → MR → matching-head CI/EvidencePack, with no manual Codex CLI interaction.