docs: refresh README and realign published docs with current features

[cnjack]

Summary

• Rewrite the README and audit the published docs/ site against the current code, fixing drift between docs and shipped behavior.
• Surface shipped-but-undocumented features (themes, session goals, Docker workspaces, automations, desktop app) and add the desktop screenshot.
• Move internal design docs out of the published Jekyll site into internal-doc/.

Related Issues / Tickets

Type of Change

• Documentation update

Changes Made

README — restructured into Why / Install / Features / Interfaces / Reference / Configuration; added status badges and a one-shot + CLI quickstart; documented /theme, /goal, Docker workspaces, automations and the desktop app; corrected the slash-command, keyboard-shortcut and configuration tables to match the code; added the desktop app screenshot.

Published docs (verified against code before each edit):

1. tools/execute.md, tools.md — background commands require approval (security hardening); corrected the auto-approved safe-command set (cat/echo/which/bare env/git diff/git show, foreground-only).
2. commands.md — removed --doctor/--version from the flags table (they are subcommands); added jcode automation, jcode mcp login, --open, the MCP OAuth flags, and the /channel /mcp /help /submit-pr slash commands.
3. configuration.md — documented context_limits, default_context_limit, docker_aliases; clarified the auto_approve → default_mode deprecation and the retired ask/agent/autopilot mode IDs; kept the JSON reference example valid.
4. changelog.md — synced the Unreleased section (themes, Docker workspaces, mode rename) with the root CHANGELOG.
5. overview.md, overview/skills.md, overview/models.md, tools/task-management.md — added Docker workspaces + themes, the fourth built-in skill (/submit-pr), per-model reasoning, and the goal_* tools.
6. Moved automations-prd.md and web-task-architecture.md to internal-doc/ and fixed the cross-references.

Testing

• Verified every documented command/flag/config key/tool against the source (internal/..., cmd/jcode/main.go, CHANGELOG.md).
• Confirmed image references resolve, {% link %} targets exist, and the <details> block is balanced.
• Jekyll build not run in this environment; reviewers can verify with cd docs && bundle exec jekyll build.

Screenshots / Recordings

Desktop app screenshot added at docs/asset/desktop-screenshot.png; agent-teams screenshot refreshed.

Checklist

• My code follows the project's style guidelines.
• I have performed a self-review of my code.
• I have added/updated tests as needed.
• I have updated relevant documentation.
• All new and existing tests pass.

Additional Notes

• overview/mcp.md was intentionally left unchanged: the MCP client sse transport is still supported (verified in internal/command/mcp.go, mcp_oauth.go, config.go, server.go). It is distinct from the removed web event-stream SSE (SSEBroker//api/events), which never lived in this page.
• task_get/task_list/task_stop were deliberately not documented: they only register for the coordinator subagent when a TaskManager is injected, which no shipped frontend currently does.
• docs/model-research.md was kept in docs/ because it is referenced from code comments (internal/model/registry.go, chatmodel.go).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added Docker workspace support for web-based remote connections.
  • Introduced built-in color themes with live preview and theme switching.
  • Expanded support for goals, automations, MCP login, and additional slash commands.

• Bug Fixes

  • Improved session resume and context handling guidance.
  • Clarified safer command approval behavior, including background task handling.

• Documentation

  • Refreshed setup, configuration, tools, and command docs with updated examples and usage details.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Documentation-only update refreshing the README, changelog, commands, configuration, overview, models, skills, tools, and task-management docs. New features documented include color themes, Docker workspaces, MCP OAuth, automation management commands, the Submit PR skill, Goals tool, updated execute approval policy, and new configuration fields (docker_aliases, context_limits, default_mode).

Changes

Documentation Refresh

Layer / File(s)	Summary
New capabilities in overview, changelog, and Goals tool docs/overview.md, docs/changelog.md, docs/tools/task-management.md	Adds Docker Workspaces and Color Themes rows to the core capabilities table; changelog Unreleased section replaces old bullets with entries for unified themes, /theme TUI command, web appearance settings, and Docker container workspaces; new Goals tool section documents goal_set/goal_get/goal_update, status lifecycle, and approval requirements.
Execute approval policy docs/tools/execute.md, docs/tools.md	Revises approval matrix so background tasks and non-safe commands require approval; expands safe command list (cat, echo, which, env, git read-only commands); adds safe-command matching rules and explicit env CMD ... exception; adds webfetch to auto-approved Delegation category.
Submit PR skill docs/overview/skills.md	Updates built-in skill count to four and documents the Submit PR (/submit-pr) skill: branch handling, Conventional Commit format, gh pr create invocation, URL reporting, and no-force-push constraint.
Configuration: new fields and migration docs/configuration.md	Expands the full config JSON example with default_mode, context_limits, default_context_limit, and docker_aliases; documents per-model context window override precedence and fallback rules; adds docker_aliases fields; reworks auto_approve docs with migration note for old mode IDs.
CLI subcommands and slash commands docs/commands.md	Documents jcode mcp login (OAuth), full jcode automation management subcommands, --open web flag (replaces --doctor/--version), MCP add --scope/--oauth/--client-id/--client-secret flags, and new TUI slash commands (/channel, /mcp, /help, /submit-pr).
Reasoning effort and provider runtime docs docs/overview/models.md	Fills out Reasoning & Extended Thinking section with reasoning_effort config tiers, gateway thinking toggle, and effort_overrides precedence; expands Add Provider at Runtime with web UI Settings view details and custom model reasoning-effort controls.
README comprehensive refresh README.md	Rewrites hero/install, first commands, update (including Windows note), features, session modes, SSH/Docker aliases, automations, MCP integration, skills, context management, subagents, session resume, interfaces (Terminal/Web/Desktop/Editor ACP), CLI reference, slash commands, and configuration table.
Internal doc link fix internal-doc/automations-prd.md	Updates [[web 任务化架构]] link from docs/web-task-architecture.md to internal-doc/web-task-architecture.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hop hop, the docs grow wide,
Docker and themes now inside,
Goals and skills, OAuth too—
The rabbit typed the whole thing through.
With slash commands fresh and bright,
Every feature sees the light! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main documentation refresh and alignment with current shipped features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-and-docs-refresh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cnjack]

Staff Engineer Review — PR #104

Docs-only change, so the review focuses on: whether documented behavior is accurate, whether security properties are stated correctly, and whether breaking changes are adequately communicated to users.

Five real issues found. Two are high enough severity to warrant fixes before merge.

---

Finding 1 (High) — Mode ID breaking change silently falls back with no warning documented

Background: v0.5.0 introduced default_mode with values ask/plan/autopilot. The Unreleased release immediately retires those IDs in favour of approval/plan/full_access.

Problem: docs/configuration.md says:

An unrecognized value falls back to approval.

Nothing in the docs — or in the CHANGELOG — says whether jcode emits a startup warning when it encounters a stale mode ID. If the code is silent, a user who set "default_mode": "autopilot" in v0.5.0 will silently lose auto-approve behaviour and start seeing approval dialogs on every tool call with no explanation.

Suggested fix:

1. Verify whether internal/config emits a log/stderr warning when an unrecognised mode ID is found. If it doesn't, that is a code defect that should land before this doc ships.
2. If it does warn, add a sentence: "jcode prints a warning at startup when a stale mode ID is detected."
3. The two-release promotion/deprecation cycle (ask introduced in 0.5.0, gone in the very next release) deserves a dedicated upgrade callout in the Changelog "Changed" entry, not just a config-page footnote.

---

Finding 2 (High) — bare env documented as auto-approved but it prints the full process environment including secrets

Problem: docs/tools/execute.md and docs/tools.md classify env (bare) as a safe, auto-approved command. But env outputs the complete process environment — which in CI pipelines, Docker workspaces, and developer shells routinely contains OPENAI_API_KEY, GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, and similar. The output enters the agent's context and is persisted to session JSONL and (if configured) forwarded to Langfuse.

Users running jcode in "Ask for approval" mode with secrets in their environment have a reasonable expectation that the agent cannot silently read those secrets. The docs as written call this "safe" with no caveat.

Suggested fix: Add a callout in execute.md alongside the existing shell-operator note:

> **Note:** `env` (bare) prints the full process environment, including any secrets
> injected as environment variables (`OPENAI_API_KEY`, `GITHUB_TOKEN`, etc.).
> In "Ask for approval" mode this call is auto-approved. If your environment
> contains sensitive credentials, consider unsetting them before starting jcode
> or using a wrapper script to strip secrets from the environment.

If auto-approving bare env is considered genuinely unsafe, removing it from the safe list is a code change — but at minimum the docs must stop calling it unconditionally "safe."

---

Finding 3 (Medium) — webfetch promoted to auto-approved with no security rationale or changelog entry

Problem: docs/tools.md adds webfetch to the auto-approved delegation tier:

-| **Delegation** | subagent, check_background | Auto-approved |
+| **Delegation** | subagent, check_background, webfetch | Auto-approved |

The CHANGELOG Security section in [0.5.1] carefully explains the reasoning behind every approval-gate decision (background commands, shell-operator matching, etc.) — but webfetch auto-approval appears only in this docs PR with no code-side entry. Two scenarios:

• webfetch was already auto-approved before this PR → docs catch-up, fine, but say so.
• webfetch was not previously auto-approved → this is an undocumented policy change. Silently allowing arbitrary outbound HTTP in "Ask for approval" mode is a data-exfiltration and prompt-injection escalation risk.

Suggested fix: Verify against the source. If it was already the policy, note (auto-approved since v0.x). Either way, add a security note analogous to the background-command rationale explaining what limits (if any) apply.

---

Finding 4 (Medium) — --doctor / --version flag removal has no migration callout

Problem: docs/commands.md silently removes --doctor and --version from the flags table. CI scripts, Docker ENTRYPOINT health checks, and install verification scripts commonly use jcode --version. No note directs users to the subcommand equivalents.

Suggested fix: Add a line under the flags section:

Previously available as --doctor and --version flags; use jcode doctor and jcode version (subcommands) instead.

If both forms still work (common with cobra/urfave), clarify that rather than removing the entry entirely.

---

Finding 5 (Medium) — Docker workspace docs omit privilege and credential exposure risks

Problem: The Docker workspace feature is documented purely as a convenience feature. docker exec runs as the container's default user (often root). If DOCKER_HOST points at a remote TCP socket without mutual TLS, the daemon is reachable over the network. Containers with the Docker socket mounted or --privileged set give the agent effective host-level access. execute.md has careful security notes; Docker workspace docs have none.

Suggested fix: Add a callout to configuration.md and the README Docker section:

Security: docker exec runs as the container's default user (often root). Avoid mounting the Docker socket inside agent containers. For agent workspaces use a purpose-built image with a restricted user.

---

Overall Risk

Low for the codebase (docs-only). Medium for users — two findings describe silent behavioral regressions (#1) or security properties that are documented inaccurately (#2).

#	Issue	Severity
1	Silent mode-ID fallback with no startup warning documented	High
2	bare env called "safe" and auto-approved, but reads the full process environment including injected secrets	High
3	webfetch auto-approval has no security rationale and no code changelog entry	Medium
4	--doctor/--version flag removal with no migration path	Medium
5	Docker workspace missing privilege/credential exposure warning	Medium

Items #3–5 can be addressed inline. Findings #1 and #2 need either a code-side confirmation (does the binary actually warn on stale config?) or a security note before the docs should ship as written.

---

Generated by Claude Code