Record local branch decisions

[makoMakoGo]

关联 issue：Closes #39

变更

• 新增 CONTEXT.md，记录 personal/local-clients 分支的目标、词汇、已定决策和非目标。
• 新增 docs/adr/ 下 5 条短 ADR：
  • no silent fallback
  • Claude placeholder 不是 Synthetic source
  • Pi 与 OMP 保持独立 client/source
  • cwd workspace attribution 是分支行为
  • 后续 client catalog、adapter、aggregation、TUI interaction 的边界

原因

我们会频繁 merge 上游，所以需要把本分支的 load-bearing decisions 写在 repo 内，而不是靠口头记忆。尤其是 synthetic.new 与 Claude Code model = "<synthetic>" placeholder 的语义必须分开，否则后续 agent 或 bot review 很容易把它们混成一个概念。

验证

• git diff --check

依赖关系

这个 PR 应先于删除 synthetic.new 的实现 PR 合入，用作后续 review 和冲突处理的本地决策依据。

Summary by Sourcery

Document local branch context and architectural decisions for the personal/local-clients fork to guide future changes and upstream merges.

Documentation:

• Add CONTEXT.md capturing vocabulary, branch-specific decisions, architecture direction, and non-goals for the personal/local-clients branch.
• Add five short ADRs documenting policies on no silent fallback, separating Claude placeholder from Synthetic source, treating Pi and OMP as distinct clients, defining cwd-based workspace attribution, and establishing local client and aggregation boundaries.

[sourcery-ai]

Reviewer's Guide

Documents branch-specific context and architectural decisions for the personal/local-clients fork by adding a branch context file and five concise ADRs that codify local semantics around synthetic usage, error handling, client identities, workspaces, and future client/aggregation/TUI boundaries.

File-Level Changes

Change	Details	Files
Add a branch-level context document that defines vocabulary, load-bearing local decisions, and non-goals for the personal/local-clients fork.	Introduce CONTEXT.md describing the purpose of the personal/local-clients branch and its precedence over upstream semantics when they conflict with local needs. Define core vocabulary for source, client, model_id, and workspace to standardize terminology across the fork. Codify specific decisions around no silent fallback, treating Claude "" as malformed placeholder cleanup, removing upstream synthetic.new as a client/source concept, keeping Pi and OMP as separate identities, and treating cwd workspace attribution as branch behavior shared by reports and TUI. List explicit non-goals such as not mirroring all upstream client ideas, not preserving rejected compatibility shims, and not hiding parsing/scanning/pricing/aggregation errors.	CONTEXT.md
Introduce ADRs to capture key local architectural and behavioral decisions for future implementation and upstream merge conflict resolution.	Add ADR 0001 to forbid silent fallback, fake success, swallowed errors, or defensive degradation, requiring failures to surface via errors, logs, or tests and recommending removal or explicitization of upstream fallbacks that change local semantics. Add ADR 0002 to distinguish Claude Code's "" placeholder cleanup from the upstream synthetic.new source/client concept, keeping drop logic for the placeholder while removing synthetic.new from filters, defaults, UIs, and docs, and moving any useful pricing normalization into explicit helpers. Add ADR 0003 to keep Pi and OMP as separate client/source identities for display, filtering, aggregation, and reports, requiring future client catalog work to preserve distinct ids and display facts even if internal helpers are shared. Add ADR 0004 to define cwd-based workspace attribution as explicit branch behavior implemented in core code shared between reports and TUI, with tests ensuring attribution consistency and avoiding silent mapping of unknown workspaces. Add ADR 0005 to set direction for local client boundaries: client identity via a small catalog, per-client parse adapters, a shared core usage aggregation module, and a TUI interaction seam for scroll/hitbox/selection; emphasizing incremental, slice-by-slice migrations over large speculative rewrites.	docs/adr/0001-no-silent-fallback.md docs/adr/0002-claude-placeholder-is-not-synthetic-source.md docs/adr/0003-pi-and-omp-are-separate-clients.md docs/adr/0004-cwd-workspace-attribution.md docs/adr/0005-local-client-boundaries.md

Possibly linked issues

• Record branch decisions in CONTEXT and ADRs #39: The PR adds CONTEXT.md and ADRs capturing all specified branch decisions and meeting the issue’s acceptance criteria.
• Record branch decisions in CONTEXT and ADRs #39: They match: the PR creates CONTEXT.md and ADRs to record local-branch decisions required by the issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e5acdf02-d44b-4e8c-b098-20967fb2d18f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/decision-records

---

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 and usage tips.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request introduces a branch context document (CONTEXT.md) and five Architecture Decision Records (ADRs 0001-0005) that establish vocabulary, architectural boundaries, and design decisions for the personal/local-clients branch of tokscale. The review feedback suggests minor improvements for consistency and formatting, specifically changing 'Synthetic' to lowercase 'synthetic' in ADR 0002 and wrapping 'cwd' in backticks in CONTEXT.md and ADR 0004 to clearly denote it as a technical term.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.