# Trading Redesign + Platform Audit Completion Checklist

Last updated: 2026-05-04

This document is the execution checklist for driving the trading redesign and
platform audit to high-quality completion. The source-of-truth status tables
remain `docs/AUDIT_REDESIGN.md` in this repo and
`/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`
in the platform repo. Use this checklist to decide what to do next, what "done"
means, and which gates must pass before pushing.

## Operating Rules

- Work top-down unless the human explicitly reprioritizes.
- Keep one audit item, or one tightly coupled bucket, per implementation commit.
- Tick the audit table after the implementation commit and record the short hash
  of the implementation commit in the audit row.
- Source `~/.zshrc` in every shell before package-manager commands so
  `GITEA_NPM_TOKEN` is available.
- Do not touch platform nomgap WIP files:
  `docker-compose.ecosystem.yml`, `products/nomgap/product.json`,
  `services/platform-service/src/modules/flags/seed.ts`.
- Do not commit incidental lockfile changes except when the audit item
  specifically owns the lockfile.
- Do not skip verification gates, even for docs-adjacent changes that alter the
  audit workflow.
- If a change alters public API contracts, exported schemas, endpoint payloads,
  or auth behavior, pause and confirm unless the audit item explicitly requires
  that contract change.

## Fresh-Agent Start Procedure

Every agent should do this before writing code:

1. Read `docs/CODEX_RESUME_PROMPT.md` in full.
2. Read `docs/AUDIT_REDESIGN.md` and this checklist.
3. If touching platform, also read
   `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md`
   and
   `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`.
4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN`.
5. Run `git status --short`; stop if there are unexpected local edits in files
   you need to touch.
6. Run `git pull --ff-only` so the local branch includes any other agent's
   completed rows and commits.
7. Confirm the target audit row is still open and no other agent has pushed it.
   If the row is already `✅`, skip it and take the next assigned row.
8. Inspect the files you expect to edit and confirm they do not overlap with an
   active parallel stream.
9. Run the relevant baseline gates before making code changes when the work is
   not docs-only.
10. Implement only the assigned item or bucket.
11. Run the full relevant gates again.
12. Commit the implementation first.
13. Run `git pull --rebase --autostash` again before editing audit docs. If it
    conflicts, resolve only if the conflict is simple and in docs; otherwise
    stop. If a rebase applies remote code changes, rerun gates before the doc
    tick. Recompute the implementation hash after any rebase.
14. Update the audit row status and fix commit with the final short
    implementation hash, then commit the doc tick separately.
15. Run final gates after both commits.
16. Run `git pull --rebase --autostash` one last time before `git push`. If it
    applies remote commits, rerun the final gates before pushing.
17. Push both commits.
18. Report the item id, implementation commit hash, doc tick commit hash, and
    gate output in three sentences or fewer.

## Work Claiming and Collision Handling

- The assignment prompt is the claim. Do not create a claim-only commit unless
  the human explicitly asks for one.
- Before starting, check `git log --oneline -10` and the audit table. Another
  agent may have finished the item while your session was idle.
- If another agent lands the same item first, do not duplicate it. Pull, verify
  the row is `✅`, and move to the next assigned item only if the prompt allows
  continuing.
- If your implementation files overlap with another active stream, pause and
  ask for an integrator decision. The most common overlap files are
  `web/src/views/HomeView.tsx`, strategy-builder components, backend API route
  helpers, and audit docs.
- If only the audit doc conflicts, preserve all completed rows and all commit
  hashes. Never erase another agent's row update.
- If a package manager changes a lockfile you do not own, revert only that
  incidental lockfile hunk before committing. Do not revert unrelated human or
  agent edits.

## Report Format After Each Push

Use this exact shape:

```text
<ITEM> pushed: implementation <hash>, docs <hash-or-none>.
Gates: <gate 1 result>; <gate 2 result>; <gate 3 result>; <gate 4 result>.
Next: <next queue item or blocker>.
```

Example:

```text
B2+B3 pushed: implementation abc1234, docs def5678.
Gates: web typecheck exit 0; web build ✓ built; web test 155/155; backend tsc exit 0.
Next: C2 FMP cache.
```

## Multi-Row and Newly Discovered Work

- If one cohesive fix closes multiple audit rows, commit it once with all IDs in
  the subject, for example `fix(B2,B3): wire ticker header actions`.
- In the audit table, put the same implementation hash in each closed row.
- If you discover a real issue that is not in the audit, do not quietly broaden
  scope. Add a new audit row or a checklist note in a docs commit, then ask the
  human to prioritize it unless it blocks the current item.
- If an item's acceptance criteria are ambiguous, inspect existing code and docs
  first. If still ambiguous and the fix changes user-visible behavior or public
  contracts, pause and ask.

## Exact Commit and Audit Update Loop

Use this loop for every trading audit item:

```bash
source ~/.zshrc
export GITEA_NPM_TOKEN
git status --short
git pull --ff-only

# Baseline gates before substantial code changes
npm --prefix web run typecheck
npm --prefix web run build
npm --prefix web test
npx tsc --noEmit -p backend/tsconfig.json

# Edit files, then repeat gates
npm --prefix web run typecheck
npm --prefix web run build
npm --prefix web test
npx tsc --noEmit -p backend/tsconfig.json

git add <implementation-files>
git commit -m "fix(B2,B3): short description" \
  -m "Present-tense why paragraph." \
  -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \
  -m "Co-Authored-By: GPT-5 Codex <noreply@openai.com>"

git pull --rebase --autostash
# If the rebase applies remote code changes, rerun the relevant gates before editing docs.
IMPLEMENTATION_HASH="$(git rev-parse --short HEAD)"
# Edit docs/AUDIT_REDESIGN.md: ⬜ -> ✅ and Fix commit -> $IMPLEMENTATION_HASH
git add docs/AUDIT_REDESIGN.md
git commit -m "docs(B2,B3): tick ticker header audit rows" \
  -m "Record the implementation commit in the redesign audit table." \
  -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \
  -m "Co-Authored-By: GPT-5 Codex <noreply@openai.com>"

# Final gates after both commits
npm --prefix web run typecheck
npm --prefix web run build
npm --prefix web test
npx tsc --noEmit -p backend/tsconfig.json

git pull --rebase --autostash
# If the rebase applies remote commits, rerun the final gates before pushing.
git push
```

Do not amend the implementation commit to include the audit-row hash after the
hash is written into the table. That creates a self-referential hash loop. The
preferred pattern is one implementation commit plus one small docs tick commit.

For docs-only work, use the same commit style but run at least
`git diff --check` and the trading gates unless the human explicitly waives
them.

## Parallelization Rules

Maximum parallel streams: 3 agents.

- Parallel streams must own disjoint files or clearly disjoint repos.
- Only one agent may edit `docs/AUDIT_REDESIGN.md` at a time. If multiple
  agents finish together, each should pull/rebase first, then update only its
  own rows.
- Do not parallelize two items that both touch `web/src/views/HomeView.tsx`,
  shared strategy-builder files, or backend route helpers unless one agent is
  explicitly acting as integrator.
- Prefer one frontend feature stream, one backend/security/test stream, and one
  platform-lint stream.
- Each agent must push incremental commits for its owned item before taking the
  next item.
- If a gate fails in code outside the agent's touched files, stop and report
  instead of masking the failure.
- If merge conflicts appear in audit docs only, resolve by preserving all
  completed rows and commit hashes.

Recommended three-way split for the current backlog:

| Stream | Owns | Avoids |
| --- | --- | --- |
| Agent 1 - Web feature | `B2+B3`, then `B4+B5`, then `B6-B10` | Backend route/cache files and platform repo |
| Agent 2 - Backend/security/tests | `C2`, `F6`, `C1`, then `C3-C7` | `TickerHeader`, layout polish, platform repo |
| Agent 3 - Platform/infra/docs | Platform `P-sweep`, then `E1/E3/E4` if platform is blocked | nomgap WIP files and active trading feature files |

If only two agents are available, run Agent 1 and Agent 2. If only one agent is
available, follow the recommended next commits top-down.

## One-Line Parallel Agent Prompts

Agent 1:

```text
In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement B2+B3 only: wire TickerHeader Watchlist/alert actions and company name from fetchResearchProfile; run all trading gates, commit implementation, tick only B2/B3 rows with the implementation hash in a docs commit, push, and report hashes plus gate output.
```

Agent 2:

```text
In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement C2 only: add a 30-minute in-memory FMP cache keyed by full upstream URL with tests where practical; run all trading gates, commit implementation, tick only C2 with the implementation hash in a docs commit, push, and report hashes plus gate output.
```

Agent 3:

```text
In /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat, read docs/HANDOVER.md and docs/AUDIT_PLATFORM.md plus the trading docs/COMPLETION_CHECKLIST.md, then do one package-scoped P-sweep lint fix only without touching nomgap WIP or platform pnpm-lock.yaml; run platform typecheck/test/lint, commit that package only, update AUDIT_PLATFORM.md if applicable, push, and report hashes plus before/after lint error count.
```

## Current Snapshot

Completed in trading:

- [x] `A1-A6` Critical integration repairs.
- [x] `E2` Root pnpm lockfile includes redesigned web dependencies.
- [x] `F7-F8` Previously known web test failures fixed; web suite is fully green.
- [x] `B1` RSI, MACD, and Bollinger indicator toggles are wired in `StockChart`.

Open high-priority trading work:

- [ ] `B2+B3` Wire `TickerHeader` Watchlist/alert buttons and real company name.
- [ ] `C2` Add in-memory FMP cache.
- [ ] `F6` Add backend endpoint coverage for the new market/research endpoints.
- [ ] `C1` Refuse or sandbox code strategy backtests.
- [ ] `B6` Persist `CodeStrategyEditor` saves through canonical profile APIs.
- [ ] `D1` Replace plain loading copy with skeleton loaders.
- [ ] `D5` Add responsive web layout behavior.

Open platform work:

- [ ] `P-sweep` Clear the 85 surfaced lint errors package-by-package.
- [ ] `R3-R4` Optional package-manager noise cleanup.

## Required Gates

Run these before claiming a trading item is complete:

```bash
source ~/.zshrc
npm --prefix web run typecheck
npm --prefix web run build
npm --prefix web test
npx tsc --noEmit -p backend/tsconfig.json
```

Expected trading result:

- `web typecheck`: exit 0.
- `web build`: exit 0 and `✓ built`.
- `web test`: 155/155 passing after `F7-F8`.
- `backend tsc`: exit 0.

Run these before claiming a platform item is complete:

```bash
source ~/.zshrc
pnpm typecheck
pnpm test
pnpm lint > /tmp/lint.log 2>&1
```

Expected platform result:

- `pnpm typecheck`: exit 0.
- `pnpm test`: all suites pass.
- `pnpm lint`: error count must go down for the package being fixed and must not
  introduce new warnings/errors elsewhere.

## Priority Work Queue

### Phase 1 - Finish Web Functional Gaps

- [ ] `B2` Wire Watchlist button.
  Acceptance: button has a real click path, visible active/inactive state,
  accessible label/title, and no misleading "saved" state before persistence.
  If no backend watchlist endpoint exists, implement a scoped local persistence
  path only if the UI copy clearly says local/watchlist preference, otherwise
  create or reuse the proper API after confirming contract.

- [ ] `B3` Pull company name from `fetchResearchProfile`.
  Acceptance: `TickerHeader` shows `companyName` when available, falls back to
  symbol when unavailable, handles loading/error without layout jump, and avoids
  duplicate FMP calls when `ResearchCards` already fetches the same profile.

- [x] `B4` Use latest chart bar timestamp for "as of". Implementation: `311d79c`.
  Acceptance: header timestamp is derived from market data, not wall-clock
  render time. Fallback is explicit when no bars exist.

- [x] `B5` Compute QuickStats for searched symbols. Implementation: `27b3d1a`.
  Acceptance: RSI/EMA values populate for tickers not tracked by the bot, using
  chart bars or a shared indicator helper. Avoid duplicate indicator math drift
  between `StockChart` and `QuickStats`.

- [ ] `B6` Persist `CodeStrategyEditor` saves.
  Acceptance: Save calls canonical profile creation/update API, surfaces backend
  errors, preserves local draft behavior only as a draft/recovery mechanism, and
  saved code strategies appear where users expect to find them.

- [x] `B7` Remove or use unused `editorRef`. Implementation: `1fd1bf3`.
  Acceptance: no dead ref remains, or it powers a concrete behavior such as
  formatting/focus/save integration.

- [x] `B8` Wire visual-builder backtest action. Implementation: `1cd23f3`.
  Acceptance: `ResearchView` passes `onBacktest`, the button appears in the
  visual builder, and payload shape matches `/api/backtest/run`.

- [x] `B9` Integrate saved visual/code strategies into Strategies tab. Implementation: `70db4c9`.
  Acceptance: strategies saved in the new builders are discoverable in the
  existing Strategies tab without duplicating stores or creating divergent data
  models.

- [x] `B10` Add React Router catch-all route. Implementation: `ee7404a`.
  Acceptance: invalid paths show a useful 404/return-home state instead of a
  blank screen, with tests if routing tests already exist.

### Phase 2 - Security, Correctness, and Quota Protection

- [ ] `C2` Add FMP response cache.
  Acceptance: server-side in-memory cache uses full URL as key, TTL is 30
  minutes, concurrent callers do not stampede where reasonable, failed responses
  are not cached, and logs/metrics can distinguish cache hit/miss.

- [ ] `C1` Refuse or sandbox `strategyConfig.type === 'code'`.
  Acceptance: `/api/backtest/run` cannot execute arbitrary unsandboxed user JS.
  Minimum acceptable fix is a clear 400 response for code strategies with a user
  safe error message and a test proving refusal. A sandbox implementation needs
  resource limits, timeout, no filesystem/network access, and malicious-code
  tests.

- [ ] `C3` Validate screener sector query.
  Acceptance: unsupported sectors are rejected or ignored predictably, FMP calls
  receive only allow-listed sector values, and the frontend handles validation
  errors cleanly.

- [ ] `C4` Validate news symbols query.
  Acceptance: symbols are normalized, length-limited, and restricted to expected
  equity/crypto symbol formats before proxying to Alpaca.

- [ ] `C5` Pause market-index polling when tab is hidden.
  Acceptance: polling stops while `document.visibilityState === 'hidden'`,
  resumes on visible, cleans up event listeners, and does not double-create
  intervals after route changes.

- [ ] `C6` Remove FMP demo-key ambiguity.
  Acceptance: `.env.example`, runtime config, and server fallback agree on how
  missing `FMP_API_KEY` behaves. Prefer explicit missing-key failure for
  production and documented demo-only local behavior.

- [x] `C7` Mitigate FMP key exposure. Implementation: `e2e189e`.
  Acceptance: cache from `C2` is in place, logs avoid printing full FMP URLs
  with `apikey`, and docs explain that FMP requires query-string auth.

### Phase 3 - Tests and Regression Nets

- [ ] `F6` Backend tests for new endpoints.
  Acceptance: tests cover `/api/chart/bars`, `/api/news`,
  `/api/market/indices`, `/api/research/profile`, `/api/research/metrics`,
  `/api/research/earnings`, and `/api/screener`. Include happy path, upstream
  failure, auth/validation behavior, and crypto chart routing where applicable.

- [ ] `F1` Tests for `web/src/lib/marketApi.ts`.
  Acceptance: authenticated headers, request-id header, URL encoding, success
  parsing, and error body fallback are covered.

- [ ] `F2` Tests for `VisualRuleBuilder.tsx`.
  Acceptance: rule add/remove/reorder/edit flow, save payload shape, validation,
  and error state are covered.

- [ ] `F3` Tests for `CodeStrategyEditor.tsx`.
  Acceptance: run-backtest payload shape, save behavior after `B6`, error
  display, and local draft/recovery semantics are covered.

- [ ] `F4` Tests for `HomeView.tsx`.
  Acceptance: chart fetch path, indicator toggles from `B1`, profile cards,
  loading/error/empty states, and ticker switching are covered without brittle
  Recharts internals.

- [ ] `F5` Tests for `ScreenerView.tsx`.
  Acceptance: filter, sort, selected sector, row click, loading/error/empty
  states, and validation behavior from `C3` are covered.

### Phase 4 - UX Polish and Web Quality

- [ ] `D1` Skeleton loaders.
  Acceptance: News, ResearchCards, and Screener use stable skeleton layouts
  instead of plain "Loading..." text and avoid layout jump.

- [ ] `D5` Responsive layout.
  Acceptance: below 1024px the sidebar collapses or becomes a top/bottom nav,
  the right panel hides or moves behind an affordance, content remains usable at
  tablet and phone widths, and no horizontal scroll appears for primary flows.

- [x] `D2` Light-theme contrast in legacy tabs. Implementation: `5ca8183`.
  Acceptance: Settings, Config, and other legacy tabs meet readable contrast in
  the redesigned light shell without regressing dark-styled components that are
  still intentionally dark.

- [x] `D3` Remove hard-coded exchange. Implementation: `1e502b9`.
  Acceptance: exchange comes from profile/market metadata when available and
  falls back to a neutral placeholder, not always `NASDAQ`.

- [x] `D4` Highlight selected Screener sector from "More sectors". Implementation: `3bf1ca7`.
  Acceptance: the selected sector is visually reflected in pills/select state,
  keyboard and screen-reader state remains clear, and sorting/filtering remains
  unchanged.

- [x] `D6` Clean up editor timers. Implementation: `2089b9a`.
  Acceptance: `VisualRuleBuilder` and `CodeStrategyEditor` clear any save/status
  timers on unmount and do not set state after unmount.

- [x] `D7` Keyboard shortcuts. Implementation: `1b2130e`.
  Acceptance: Cmd/Ctrl-K focuses search, Cmd/Ctrl-S saves in code editor,
  Cmd/Ctrl-Enter runs backtest where relevant, shortcuts are discoverable, and
  inputs/textareas do not receive surprising global behavior.

- [x] `D8` Crypto-aware empty-state ticker chips. Implementation: `b1f872f`.
  Acceptance: suggested chips reflect the active bot/config market type or use
  a mixed set with clear labels.

- [x] `D9` Reduced-motion support. Implementation: `fce0228`.
  Acceptance: spinners/animations respect `prefers-reduced-motion`, preserving
  status clarity without continuous animation.

### Phase 5 - Build, Docs, and Deployment Hardening

- [x] `E1` Lazy-load Monaco. Implementation: `8a8c313`.
  Acceptance: code editor chunk is loaded only when needed, bundle size drops
  meaningfully, loading fallback is polished, and editor tests still pass.

- [x] `E3` Bundle Monaco workers locally. Implementation: `e8b3c9c`, `e266a8b`.
  Acceptance: Vite config serves TS/JSON/CSS/HTML workers locally, no runtime
  CDN worker dependency remains, and CSP/offline deployment notes are updated.

- [ ] `E4` Document redesigned web layout and env vars.
  Acceptance: README or docs describe routes, env vars including `FMP_API_KEY`,
  data providers, local dev setup, and known operational limits.

- [ ] Handover refresh.
  Acceptance: `docs/HANDOVER.md` reflects current reality: E2, F7-F8, and B1
  are done; web tests are 155/155; next item is correct.

- [ ] Release smoke checklist.
  Acceptance: add or refresh a manual smoke checklist for dashboard load,
  ticker search, chart periods, indicators, news, research cards, screener,
  strategy builder, backtest run, save flows, and auth expiry.

### Phase 6 - Mobile Parity

- [ ] `G4` Mobile runtime/client exposes new endpoints.
  Acceptance: mobile has a typed way to call news, indices, research, screener,
  and chart endpoints without duplicating fragile URL construction.

- [ ] `G2` Mobile data provider fetches new market context.
  Acceptance: `TradingDataProvider` or an equivalent mobile data layer fetches
  news, indices, and company profile with loading/error states.

- [ ] `G1` Mobile tabs for new web features.
  Acceptance: Expo app exposes news, research, and screener experiences in a
  mobile-native layout. Code editor remains web-only unless explicitly approved.

- [ ] `G3` Mobile visual strategy builder decision.
  Acceptance: either ship a mobile visual-builder MVP or document why it is
  deferred, with UX constraints and web handoff path.

- [ ] Mobile verification.
  Acceptance: mobile typecheck/lint pass, major screens render in simulator or
  Expo web as appropriate, and no web-only APIs leak into native paths.

### Phase 7 - Platform Audit Completion

- [ ] Platform P-sweep package inventory.
  Acceptance: regenerate `/tmp/lint.log`, list packages with current lint error
  counts, and choose one package at a time.

- [ ] Platform `services/platform-service` lint fix.
  Acceptance: run package-scoped `lint:fix` where safe, eyeball public exports,
  manually rename intentionally unused args with `_`, and commit only that
  package's owned changes.

- [ ] Platform `services/extraction-service` lint fix.
  Acceptance: same package-scoped workflow; preserve tests and public API.

- [ ] Platform `services/cowork-service` lint fix.
  Acceptance: same package-scoped workflow; no nomgap WIP files touched.

- [ ] Platform `packages/auth` lint fix.
  Acceptance: unused values removed only when not public API; otherwise `_`
  prefix or targeted eslint disable with rationale.

- [ ] Platform `packages/llm` lint fix.
  Acceptance: maintain exported interfaces and provider contract behavior.

- [ ] Platform `packages/cosmos` lint fix.
  Acceptance: no data-access behavior changes; tests/typecheck pass.

- [ ] Platform dashboard lint fixes.
  Acceptance: `dashboards/admin-web` and `dashboards/tracker-web` are handled
  in separate commits if both need edits.

- [ ] Platform final lint gate.
  Acceptance: workspace lint error count reaches zero, or all remaining errors
  are explicitly documented with owner/justification and approved by the human.

- [ ] Platform R3/R4 cleanup.
  Acceptance: `.npmrc` token warning is quieted safely if feasible, and
  `@azure/core-client` peer warnings are resolved only if dependency owners
  accept the explicit dependency.

## Quality Bar Before Calling the Work Complete

- [ ] All trading audit rows are `✅` or explicitly documented as deferred with
  owner, reason, and revisit date.
- [ ] All high/critical security rows are either fixed or explicitly refused by
  design with tests.
- [ ] Trading web typecheck/build/test and backend typecheck pass from a clean
  checkout.
- [ ] Platform typecheck/test pass and lint debt is reduced to zero or a signed
  off exception list.
- [ ] No new private registry, lockfile, or vendored-package drift is present.
- [ ] README/HANDOVER/resume prompt reflect current status and no longer mention
  stale known failures.
- [ ] Browser smoke pass covers desktop and mobile-width web layouts.
- [ ] Mobile parity gaps are closed or explicitly scoped into a follow-up
  milestone with user approval.
- [ ] Production-sensitive configs are documented: Alpaca, FMP, auth runtime,
  request IDs, rate limits, and cache behavior.
- [ ] Every pushed chunk has a clear commit hash, audit row update, and gate
  output recorded in the handoff conversation or docs.

## Recommended Next 10 Commits

1. `fix(B2,B3): wire ticker actions and company profile`.
2. `fix(C2): cache FMP proxy responses`.
3. `test(F6): cover market data proxy endpoints`.
4. `fix(C1): refuse unsafe code strategy backtests`.
5. `fix(B6): persist code strategy saves`.
6. `fix(D1): add dashboard skeleton loaders`.
7. `fix(D5): add responsive dashboard breakpoints`.
8. `fix(B4,B5): derive ticker freshness and quick stats from bars`.
9. `test(F1,F4): cover market client and home chart flows`.
10. `chore(E1): lazy-load Monaco editor`.

## Notes for Future Agents

- `docs/AUDIT_REDESIGN.md` is the ledger. This checklist is the playbook.
- Prefer shared helpers for indicator math and market-data normalization if
  another item needs the same calculations.
- Keep frontend UI work inside the existing visual language unless explicitly
  redesigning a surface.
- The platform repo has unrelated WIP; inspect `git status` before every
  platform package sweep and avoid those files.
- If a full recursive pnpm install is blocked by the private registry route,
  document the exact error and use the narrowest package-manager command that
  satisfies the owned item.
