feat: integrate token point usage v2

.project-docs/30-worklog/current-state.md

@@ -4,6 +4,21 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
 
 ## Integrated Through
 
+- Token Point V2 account-usage source `6348e402a4e8dde712e5cba4620bb883ffe24e0b`
+  from task `20260906-trace-makelore-usage-3d7a5c1e` is integrated onto local
+  `main` by task `20260906-integrate-token-points-v2-7b4e1c92`. The account menu
+  now uses the Main-owned `/api/works/billing/points` route and the Works Square
+  `/api/billing/points` authority instead of the retired rolling-window usage
+  contract. Managing accounts see the authoritative plan, weekly remaining/allowance,
+  total remaining points, and refresh time; loading and retrieval failures remain
+  explicit. Every non-managing account receives only coarse `shared_available`
+  state, including both family-shared members and youth self entitlements, and never
+  receives plan, cycle, or exact balance fields through the Main projection. Source
+  verification passed 72 focused tests, typecheck, scoped lint, all Vite targets,
+  diff/source checks, and two matching Works Square V2 contract tests. The deployed
+  service/database state and signed-in packaged-client smoke remain release evidence
+  gaps; no server deployment, database migration, package, publication, or remote
+  push is claimed.
 - Automatic Game Resource delivery source
   `6113a2453299141eab8420a56e93675712dd607b` from task
   `20260906-game-resource-auto-delivery-7a4e2c91` is integrated onto local `main`

.project-docs/30-worklog/tasks/20260906-integrate-token-points-v2-7b4e1c92.md

@@ -0,0 +1,75 @@
+# Task: Integrate Token Point V2 account usage
+
+## Identity
+
+- Task ID: 20260906-integrate-token-points-v2-7b4e1c92
+- Mode: Integration
+- Branch: main
+- Worktree: D:\Datas\OthersProjects\makelore
+- Base commit: 9fed0cc7c45df6b4ef01a52abc5045de478faa9c
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Integrate completed MakeLore Token Point V2 account-usage source commits
+  `8e5abd8` and `6348e40` from task
+  `20260906-trace-makelore-usage-3d7a5c1e` onto local `main@9fed0cc`.
+- Reconcile the source task's accepted promotion candidate into canonical
+  `current-state.md` without changing its source task record.
+- Preserve the already integrated Agent Browser repair and three explicitly adopted
+  untracked task records in the primary worktree.
+
+## Intent And Constraints
+
+- Preserve ADR-004: Renderer uses fixed Host API routes while Electron Main owns
+  Works Square credentials and response projection.
+- Preserve Works Square as the sole Token Point balance authority; do not restore
+  the retired five-hour or rolling-seven-day contract and do not derive ledger state
+  in Renderer.
+- Preserve the non-manager privacy boundary using `can_manage_membership`, not
+  `family_shared`, because youth self entitlements are also non-managing.
+- Apply the two source commits as patches on the latest main rather than advancing to
+  the old source branch head, which would reverse the newer Agent Browser integration.
+- Do not modify or stage the three adopted untracked task records, deploy services,
+  run migrations, package the client, publish, or push remotely.
+
+## Outcome
+
+- Re-anchored the integration at `main@9fed0cc` after the blocking Main-worktree
+  owner was explicitly released, then applied source commits `8e5abd8` and
+  `6348e40` with `--no-commit` and no conflicts.
+- Verified the staged source task record is byte-for-byte identical to source head
+  `6348e40` and registered it as an unchanged adopted foreign document.
+- Integrated the V2 points route, strict Main projection, account-menu presentation,
+  privacy handling, and focused tests without changing any Agent Browser file.
+- Promoted the durable V2 account-usage contract and remaining live-release gaps to
+  canonical `current-state.md`.
+- The three pre-existing untracked task records remain unstaged and unchanged.
+
+## Verification
+
+- Source verification is recorded in task
+  `20260906-trace-makelore-usage-3d7a5c1e`: 72 focused tests, typecheck, scoped lint,
+  all Vite targets, diff/source checks, and two matching server contract tests passed.
+- Passed the same four focused Vitest files on `main@9fed0cc` plus the staged V2
+  integration (72 tests).
+- Passed `pnpm run typecheck` and scoped ESLint over all changed TypeScript/TSX files.
+- Passed `pnpm run build:vite` for Renderer, Electron Main, preload, and utility
+  bundles. Only the repository's existing Browserslist, dynamic-import, and chunk-size
+  advisories were reported.
+- Verified the staged source task record matches source head `6348e40` and the staged
+  path set contains no Agent Browser or README file.
+- Passed task-aware project-document drift checks with the source task record and the
+  three pre-existing untracked task records unchanged.
+
+## Follow-ups
+
+- Verify that the deployed Works Square API and database are on the V2 release and
+  migration head before releasing the paired client.
+- Run a signed-in packaged-client smoke against the deployed V2 service.
+
+## Promotion Candidates
+
+- None. This Integration Gate applies the accepted source promotion directly to
+  `.project-docs/30-worklog/current-state.md`.

.project-docs/30-worklog/tasks/20260906-trace-makelore-usage-3d7a5c1e.md

@@ -0,0 +1,101 @@
+# Task: Trace current MakeLore membership and usage display values
+
+## Identity
+
+- Task ID: 20260906-trace-makelore-usage-3d7a5c1e
+- Mode: Feature
+- Branch: codex/20260906-trace-makelore-usage-3d7a5c1e-trace-makelore-usage
+- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260906-trace-makelore-usage-3d7a5c1e
+- Base commit: 5c61110f465cc4172f712ad435c06041c0aed1ec
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Trace how the account menu previously obtained membership level, five-hour usage,
+  and seven-day usage, and verify the matching Works Square contract.
+- Migrate the Renderer and Electron Main transport from the retired rolling-window
+  DTO to `GET /api/billing/points` and the Token Point V2 balance DTO.
+- Replace the obsolete percentage rows with current-week and total Token Point
+  balances, while preserving explicit loading, error, exhaustion, and family-shared
+  states.
+
+## Intent And Constraints
+
+- Keep Works credentials and billing authority in Electron Main/Works Square; the
+  Renderer only formats a safe balance projection and never derives ledger values.
+- Preserve the V2 privacy boundary: any non-manager receives only the coarse
+  `shared_available` result, not the plan, cycle, or exact balances. This includes
+  both family-shared members and youth users with a self entitlement.
+- Keep the existing Renderer -> Host API -> Electron Main -> Works Square ownership
+  chain and avoid unrelated account, runtime, or browser changes.
+- Do not modify or deploy Works Square server code from this client feature task.
+
+## Outcome
+
+- Replaced the client call with `fetchWorksTokenPointBalance`, using the local route
+  `/api/works/billing/points`; Electron Main now forwards authenticated requests to
+  Works Square `GET /api/billing/points`.
+- Added a strict Main-process V2 projection. Invalid point strings or malformed
+  entitlement metadata produce a safe 502 response, and every non-managing account
+  has plan, cycle, and exact point fields cleared even if upstream includes them.
+- The account menu now gets the membership label from V2 `plan_name`/`plan_code`,
+  removes the retired five-hour and rolling-week percentage rows, and displays
+  `weekly_remaining / weekly_allowance`, `total_remaining`, and `next_refresh_at`.
+- Loading and retrieval failures are distinct UI states. A failure no longer appears
+  as `不限` or as a fabricated zero balance, and the user can retry explicitly.
+- Shared members see `共享会员` plus only `共享额度` availability. When exhausted they
+  are directed to the family administrator and are not shown a self-service upgrade
+  action.
+- Youth users with a self entitlement also follow the coarse-availability contract:
+  they see `青少年账户`, no exact balances, and a parent-contact message instead of
+  a self-service upgrade action.
+- Removed the unused V1 percentage formatter/exhaustion helper and stale-event retry
+  module. Initial login, focus, visibility, and account-menu refreshes remain intact.
+- No Works Square server source, deployment, packaged client, or live account state
+  was changed.
+
+## Verification
+
+- Passed focused client, Main route, formatter, privacy, error-state, and Sidebar UI
+  tests:
+  `pnpm exec vitest run tests/unit/works-square.test.ts tests/unit/works-routes.test.ts tests/unit/works-square-token-points.test.ts tests/unit/sidebar-token-points.test.tsx --maxWorkers=2`
+  (4 files, 72 tests).
+- Passed `pnpm run typecheck`.
+- Passed scoped ESLint over every changed TypeScript/TSX source and test file.
+- Passed `pnpm run build:vite` for Renderer, Electron Main, preload, and utility
+  bundles. Vite reported only the repository's existing dynamic-import/chunk-size
+  advisory warnings.
+- Passed `git diff --check` and a source/test scan found no remaining account-menu V1
+  symbol, retired local route, or rolling-percentage reference.
+- The matching server contract and youth-account tests passed during the trace:
+  `tests/test_token_points.py::test_v2_billing_contract_exposes_points_and_retires_legacy_endpoints`
+  and
+  `tests/test_token_points.py::test_youth_v2_billing_is_read_only_and_rejects_reset_card_checkout`
+  (2 passed).
+
+## Follow-ups
+
+- Integrate the task branch into the intended MakeLore release branch.
+- Verify that the deployed Works Square API image and database are on the V2 release
+  and migration head; source inspection cannot establish live deployment state.
+- A signed-in packaged-client smoke against the deployed V2 service remains useful
+  release evidence; it was not run because this task does not authorize deployment,
+  installation, or live-account mutation.
+
+## Promotion Candidates
+
+- Target canonical document: `.project-docs/30-worklog/current-state.md`.
+- Proposal: record that the account menu consumes the V2 Token Point balance, shows
+  weekly remaining/allowance and total available points, has explicit loading/error
+  states, and exposes only coarse availability to every non-managing account.
+- Evidence: focused 72-test pass, typecheck, scoped lint, production Vite build, and
+  the two server V2 contract tests listed above.
+- Future impact: account-menu changes must not restore the retired rolling-window
+  endpoint or derive exact balances in Renderer; non-manager privacy remains a
+  Main/Works contract boundary, regardless of whether the entitlement is shared.
+- Semantic conflicts: none known. This replaces a client path already retired by the
+  authoritative V2 server contract.
+- Human confirmation required: no additional product choice is required; the user
+  explicitly requested the V2 migration. Canonical promotion still belongs to an
+  Integration Gate task.