Adds §11 to the v3 cross-repo UX roadmap: a 202-item, machine-parsable
checklist that coding agents flip as they ship work, with the
`learning_ai_uxui_web` showcase as the canonical visual-iteration
surface ahead of any product adoption.
──────────────────────────────────────────────────────────────────
§11 — Showcase-first workflow & live progress tracker
──────────────────────────────────────────────────────────────────
\u00a711.0 The showcase-first rule (non-negotiable 7-step recipe)
1. Scaffold in common_plat/packages/<name>/
2. Vendor snapshot to learning_ai_uxui_web/src/lib/<name>-preview/
3. Showcase route at src/app/showcase/<group>/<slug>/page.tsx
+ catalog entry in src/catalog/routes.ts
4. MSW mock any backend dependency
5. Smoke test (axe + visual-regression baseline)
6. Publish to Gitea registry; delete preview; swap imports
7. Adopt in ≥ 1 product — that PR closes the checklist row
\u00a711.1 Agent update protocol — flip `- [ ]` → `- [x]` inline with
the commit; trail the short-SHA in parentheses; multi-step
rows tracked sub-bullet by sub-bullet.
\u00a711.2 Live "Progress at a glance" block (auto-rewritten by the
counter script below).
\u00a711.3 Wave 8 Rollout — 18 items
\u00a711.4 Wave 9 Data — 42 items
\u00a711.5 Wave 10 Shells — 35 items
\u00a711.6 Wave 11 Adaptive — 26 items
\u00a711.7 Wave 12 Mobile — 26 items
\u00a711.8 Wave 13 Futurism — 39 items
\u00a711.9 Cross-cutting — 8 items
\u00a711.10 Customer-magnet demos — 8 items
───────────────────────────────
TOTAL — 202 items
Every package row carries a paired "**Showcase:**` /showcase/...`"
route entry so agents know exactly where the demo lives. Cross-
referenced with the per-product upgrade matrix in §5.
Renumbered hygiene §11 → §12. Header bumped v3.1 → v3.2.
──────────────────────────────────────────────────────────────────
scripts/count-roadmap-progress.ts
──────────────────────────────────────────────────────────────────
TypeScript node script (tsx) that:
- Parses the v3 doc, counts `- [ ]` and `- [x]` per §11.x section
- Rewrites the §11.2 fenced block in place with live counts +
bar charts + percentages
- Updates the `· \`N / M\`` suffix on every `### 11.x Wave …`
heading so per-wave totals stay accurate
- Idempotent: re-runs are no-ops when nothing changed
- Verified: emits `0 / 202 done` on initial run; "up to date"
on second run
Wired as Wave 8.A.7 (also tracked at CC.8 — should land in pre-commit
hook so the §11.2 block can never drift from reality).
Mirror in copilot/learning_ai_uxui_web follows in a paired commit.
- sync-docker-prep.sh: add MindLyst, LysnrAI, talk2obsidian to consumer list
- docker-doctor.sh: detect Python Dockerfiles (python:3.x base) and skip
Node-specific checks (pnpm/corepack, .npmrc.docker ARGs). Python base
images are now in the approved list alongside node:22-{alpine,slim}.
Refs: docker-build-optimization-roadmap.md \xc2\xa7 D
Promotes docker-prep.sh to canonical home in common-plat with full Phase B
hardening from the docker-build-optimization-roadmap:
- B1: --dry-run mode (lists actions, no side effects)
- B2: idempotency guard (refuses to run if *.bak exists, --force to bypass)
- B5: trap-based auto-restore on error (--keep to disable)
- B6: standardized header + usage block
- B7: canonical home + sync + drift-check (mirrors npmrc.template pattern)
- B8: --strip-overrides for safety-net cleanup
- New: --check mode for CI-friendly state verification
- New: auto-discovers package.json files with @bytelyst/* deps
- New: portable sed -i (BSD on macOS, GNU on Linux)
- New: preserves .docker-deps/.gitkeep on clear (fixes earlier regression)
- New: 2 small JS helpers (_docker-prep-*.js) avoid bash 3.2 heredoc quirks
Verified on clock + peakpulse: dry-run, pack, check, idempotency guard,
restore, and post-restore git status all clean.
Static linter for Dockerfile + docker-compose + .npmrc.docker drift.
Sibling to gitea-doctor. Codifies all 15 invariants from Phase A of
the docker-build-optimization-roadmap so regressions are caught at
PR time, not at build time.
Verified against both pilots:
- learning_ai_clock: PASS (1 expected warning)
- learning_ai_peakpulse: PASS (1 expected warning, pnpm-lock per ADR-0001)
- learning_ai_notes (un-migrated control): FAIL with 6 specific findings
Refs: docker-build-optimization-roadmap.md \xc2\xa7Phase E (E1, E5)
Resolves F17 in docker-build-optimization-roadmap.
Root cause:
Gitea's app.ini ROOT_URL was http://localhost:3300/. Gitea bakes
ROOT_URL into the dist.tarball field of every published package's
metadata. Inside a Docker container, 'localhost' is the container
itself, not the host \u2014 so any 'pnpm install' that needed to fetch
a tarball would ECONNREFUSED, even though the registry metadata
itself was reachable via host.docker.internal.
Server-side fix (not in git, requires manual replication on each dev
machine; documented in roadmap \u00a73 A-pre-6):
- Edit /opt/homebrew/var/gitea/custom/conf/app.ini:
ROOT_URL = http://host.docker.internal:3300/
- brew services restart gitea
- sudo sh -c 'echo "127.0.0.1 host.docker.internal" >> /etc/hosts'
Repo-side fix (this commit):
- switch-network.sh: add host.docker.internal to NO_PROXY +
NPM_CONFIG_NOPROXY when NETWORK=corp. Required so host-side curl/
pnpm/npm bypass the corporate proxy (cso.proxy.att.com) when
resolving host.docker.internal. Without this, host installs fail
with the corp proxy's 'Unknown Host' 504 page.
Republished all 64 @bytelyst/* packages so tarball URLs reflect the
new ROOT_URL:
- .publish-manifest.json: 64 entries with new content hashes
- packages/*/package.json: 64 patch-version bumps
(auto-bumped by publish-outdated-packages.sh because previous
versions already existed in registry)
Verification:
curl http://localhost:3300/.../@bytelyst%2Ferrors | jq .dist.tarball
→ http://host.docker.internal:3300/.../errors-0.1.11.tgz (was localhost:3300)
workspace:* refs across all 64 packages: 0
Unblocks: A0-V on every pilot. Verified PASSING on learning_ai_clock:
backend cold build: 59.2 s
web cold build: 3:13 (193 s)
Both via Gitea registry, no docker-prep.sh tarballs needed.
Resolves F16 in docker-build-optimization-roadmap v5.
Root cause:
publish-outdated-packages.sh uses a pack-extract-repack pattern:
1. pnpm pack (rewrites workspace:* in tarball)
2. extract
3. npm pack (re-tar from extracted content)
4. npm publish
Step 3 is the bug. npm pack does not recognize the pnpm-specific
workspace: protocol — it treats workspace:* as a literal version
string and passes it through to the final tarball. Result: any
consumer doing 'pnpm install' inside Docker (where there is no
workspace context) fails with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND.
Documented in roadmap §0 F16 + §3 Phase A-pre.
Fix (publish-outdated-packages.sh):
- Insert a workspace:* rewriter between publishConfig strip and
npm pack. Reads source package.json for each @bytelyst/* target,
resolves workspace:* / workspace:^ / workspace:~ to ^x.y.z.
- Add defense-in-depth: grep the post-rewrite package.json for any
surviving 'workspace:' literal. If found, refuse to publish.
Republished 10 affected packages with workspace:* → resolved semver:
@bytelyst/auth 0.1.5 → 0.1.6
@bytelyst/diagnostics-client 0.1.6 → 0.1.7
@bytelyst/events 0.1.5 → 0.1.6
@bytelyst/extraction 0.1.5 → 0.1.6
@bytelyst/fastify-auth 0.1.5 → 0.1.6
@bytelyst/fastify-core 0.1.5 → 0.1.6
@bytelyst/feedback-client 0.1.6 → 0.1.7
@bytelyst/field-encrypt 0.1.6 → 0.1.7
@bytelyst/react-auth 0.1.6 → 0.1.7
@bytelyst/sync 0.1.5 → 0.1.6
Verification: all 10 packages now scan with 0 workspace:* refs in
their published package.json (per registry curl scan).
Unblocks: A0-V verification on learning_ai_clock (currently blocked
at learning_ai_clock@0be887288).
Idempotent end-to-end Gitea bootstrap for Azure VM (or any Linux host
with Docker available). Replaces manual SSH-and-paste workflow.
Steps (each skippable on re-run):
1. Install Docker via official script (skip with --skip-docker)
2. Write /etc/gitea/docker-compose.yml with package registry enabled
3. Start gitea container, wait for HTTP :3300
4. Create admin user via 'gitea admin user create' (CLI inside container,
no auth bootstrap needed)
5. Create npm-user (learning_ai_user) via admin API
6. Mint npm-scoped token with write:package + read:package
Two execution modes:
- On the VM directly: scp + ssh + run
- Locally targeting remote: --ssh-host azureuser@vm
Outputs npm token to --output FILE or stdout. Prints copy-paste-ready
command for writing to ~/.gitea_npm_token_home on the workstation.
Final summary prints the doctor.sh verification command so user can
confirm registry reachability from their laptop in one step.
--dry-run shows planned actions without execution.
--force re-creates users (use after manual deletion).
Closes the 'cloud VM bootstrap' gap identified during the Gitea hardening
review — pairs with scripts/gitea/{doctor,token}.sh from commit 610a59fd.
Eliminates the three operational pain points hit in the last
owner-rename incident:
1. Owner-rename drift across 14 repos
- npmrc.template now uses ${GITEA_NPM_OWNER:-learning_ai_user}
- switch-network.sh exports GITEA_NPM_OWNER on shell start
- Future renames are a one-line env change, not 14 git commits
2. Stale shell-env tokens (file rotated, env didn't)
- scripts/gitea/token.sh: status|print|validate|rotate subcommands
- 'eval "$(bash scripts/gitea/token.sh print --export)"' refreshes
any shell without re-sourcing ~/.zshrc
- rotate uses Gitea API + macOS Keychain for admin creds
3. No pre-deploy validation
- scripts/gitea/doctor.sh: NETWORK + DNS + token consistency +
registry HTTP 200 + optional package@version probe
- Run before any deploy that needs @bytelyst/* from Gitea
Tail-end of the ts-any TODO-4 work uncovered a small class of false
positives the scanner still surfaced: ':any' that appears as TEXT inside
a string literal or JSX child, not as a TypeScript type annotation.
Examples:
const label = 'Energy: any'; // string content, not a type
<Badge>owner:any</Badge> // JSX text, not a type
Real TS ': any' annotations are followed by ',', ')', '=', ';', '>',
or end-of-line. Text occurrences are followed by alphanumeric / quote /
closing-tag delimiter characters \u2014 a clear distinguishing signal.
This commit adds a 10-line regex heuristic that skips occurrences where
':any' is followed by ' ', single quote, double quote, or '<'. The
companion AGENT_COMPLIANCE_ROADMAP.md entry for commit 79041714 already
listed this heuristic; the implementation just wasn't actually committed
at the time. This commit retroactively lands it so the working tree
matches the docs.
Verification: scripts/check-rule-violations.sh still emits 0 findings
across all 20 repos (no regression from the additional heuristic).
Per user request: 'use the local Gitea and make sure all packages
in Gitea are up to date'.
Built all packages from learning_ai_common_plat/packages/* and ran
scripts/gitea/publish-outdated-packages.sh against the local Gitea
npm registry (http://localhost:3300/api/packages/bytelyst/npm/).
Manifest-based hash comparison flagged 4 packages whose built dist/
content has changed since the last published tarball:
@bytelyst/auth-ui 0.1.5 → 0.1.6
@bytelyst/config 0.1.7 → 0.1.8
@bytelyst/dashboard-shell 0.1.5 → 0.1.6
@bytelyst/mcp-client 0.1.0 → 0.1.1
All four bumped + published successfully. Remaining 60 packages
verified up-to-date. One package skipped by design:
@bytelyst/react-native-platform-sdk (RN — not in npm publish set)
Also incidentally fixed an mcp-client build break before this run:
stale dist/ + node_modules/.cache made tsc think MCPClient was
missing a 'log' property, even though the source had been correctly
refactored to use a private 'log: McpLogger' field. A clean
'rm -rf dist node_modules/.cache && pnpm build' resolved it; no
source changes needed.
Files updated:
- packages/auth-ui/package.json
- packages/config/package.json
- packages/dashboard-shell/package.json
- packages/mcp-client/package.json
- scripts/gitea/.publish-manifest.json (new content hashes)
After this commit, every published @bytelyst/* tarball in local
Gitea matches the source tree exactly.
Previously the @bytelyst/mcp-client package logged directly to the global
`console`, which made its output invisible to consumers running under
Fastify/pino or any structured logger. The scanner exempted the whole
package for console-log findings with a TODO-3 marker; this commit
resolves the marker.
packages/mcp-client/src/index.ts:
+ Added `McpLogger` interface (debug/info/warn/error, variadic) which
is structurally compatible with the global console, pino, and
Fastify's `request.log`.
+ Added optional `logger?: McpLogger` field on MCPConfig with a JSDoc
explaining when consumers should supply their own.
+ MCPClient now stores a `private readonly log: McpLogger` field
initialised from `config.logger ?? console` in the constructor.
+ All 17 internal logging sites switched from `console.X(...)` to
`this.log.X(...)`. Mapping: console.log \u2192 this.log.info (pino
does not have a 'log' method).
scripts/check-rule-violations.sh:
- Removed the blanket /packages/mcp-client/ exemption from the
console-log scanner (TODO-3 marker comment retained for history).
- The ts-any-type exemption stays \u2014 mcp-client still uses `any` at
the JSON-RPC payload boundary (different concern).
Verification:
packages/mcp-client \u2192 `pnpm build` clean (tsc).
`bash scripts/check-rule-violations.sh` \u2192 total still 88, no new
console-log findings (mcp-client is now genuinely clean instead of
blanket-exempted).
Of 351 findings, 346 were in mac_tooling/tools/*.py (forensics CLI scripts
with __main__ blocks invoked directly). Per Q2 in
docs/AGENT_COMPLIANCE_ROADMAP.md and the mac_tooling repo's own AGENTS.md
"Differences from ByteLyst Product Repos" section, the toolkit is a
standalone CLI without the ByteLyst Fastify/structlog conventions.
Scanner refinements:
+ Repo-level exemption: learning_ai_mac_tooling (matches existing
hex-rule exemption for the same reason).
+ Honor '# noqa: T201' (flake8/ruff's print-found rule), both inline
and on the preceding line \u2014 the canonical Python opt-out for
intentional terminal output.
The remaining 5 voice_ai_agent findings fall into two categories:
- cli_output.py already had '# noqa: T201' (now respected, cleared).
- sounds.py (terminal BEL audio fallback) + fn_listener.py (user-facing
startup error on Accessibility-permission failure) get '# noqa: T201'
in the next two commits.
scripts/check-rule-violations.sh: 351 \u2192 0 b4-python-print findings.
After Tier 4 hex work the only remaining console.log findings were in
legitimate contexts. Refinements:
+ /packages/create-app/ \u2014 scaffolder CLI (prints progress to stdout)
+ /services/monitoring/ \u2014 health-check scripts (standalone CLI)
+ plugins/ \u2014 Tauri/Expo/Cowork plugin entrypoints
+ /packages/mcp-client/ \u2014 client SDK library (no Fastify logger
available; TODO-3 to inject a logger callback)
+ /packages/logger/ \u2014 the logger package itself; console IS
its implementation when no upstream is set
+ Honor 'eslint-disable no-console' block directives within 30 lines
before the offending console.log call
+ Honor 'eslint-disable-next-line no-console' on the preceding line
These match the existing scripts/ exclusion (CLI tools allowed to print)
and recognise the two extraction-service files that had explicit
eslint-disable comments documenting their dev-only purpose.
scripts/check-rule-violations.sh: 93 \u2192 0 b4-console-log findings.
Code TODOs introduced:
TODO-3 (scripts/check-rule-violations.sh comment + future work in
packages/mcp-client) \u2014 expose pluggable logger callback so
consumer apps can plumb their own logger.
Scanner refinement: recognize TS literal-type discipline pattern.
When a TS/TSX file declares:
type Doc = { productId: 'mindlyst'; ... }
the matching object-literal values:
const doc: Doc = { productId: 'mindlyst', ... }
are TYPE-SYSTEM-REQUIRED, not hardcode violations. The literal type
constrains the field at compile time; the runtime value MUST match.
This is intentional Cosmos discipline used in MindLyst's
ecosystem-phase{1,3}.ts integration modules.
Implementation: if a TS/TSX finding contains a product ID literal AND
the same file declares 'productId: "<id>";' as a type, skip the finding.
Tier 1 progress:
T1.1 voice_ai_agent churn-alert.ts \u2014 commit 2281b4b (-2 critical)
T1.2 multimodal cosmos.ts \u2014 commit 7d61713 (-1 critical)
T1.3 ecosystem-phase1.ts (5) \u2014 scanner recognizes TS pattern (-5)
T1.4 ecosystem-phase3.ts (5) \u2014 scanner recognizes TS pattern (-5)
Critical findings: 13 \u2192 0 \u2713
Total ecosystem findings: 1582 \u2192 1569. Next: Tier 2 (shared @bytelyst
packages in common_plat with ~59 hex findings).
Three precision improvements that drop total findings from 2548 to 1643
without losing real violations:
1. web-hardcoded-hex: switch from grep -oE to grep -nE so the scanner
can examine each match in CONTEXT, then apply context filters:
- Skip CSS custom property DEFINITIONS: '--bl-accent: #5A8CFF'
- Skip var(--token, #fallback) patterns: defensive design-token
fallbacks for boot-order safety, not raw hardcodes
- Skip globals.css, *.tokens.*, *Theme.{ts,tsx,swift,kt} files
- Skip design-system/ and color-picker/markdown-preview tool pages
2. b5-hardcoded-product-id: scripts/ exclusion (was previously bypassed
for the script case but still caught churn-alert.ts genuinely).
3. Updates baseline report. Findings by category:
Before After
----- -----
web-hardcoded-hex 1370 465 (-66%)
b7-emoji-in-code 465 465
b4-python-print 351 351
ts-any-type 249 249
b4-console-log 93 93
b5-hardcoded-product-id 13 13
b4-swift-print 7 7
---- ----
Total 2548 1643
Remaining hex findings are now substantively real:
- flowmonk: 114 (zone seed data: { color: '#5A8CFF' })
- fastgap: 102 (BodyCanvas organ colors, organ-data.ts)
- mindlyst: 97 (mixed UI + data)
- common_plat: 59 (brand colors in login page: Google #4285F4 etc.)
- efforise: 39
- mac_tooling: 18
These fall into three classes which will be triaged in Phase 2:
A. Brand colors (Google login etc.) - keep, document as exceptions
B. Data seeds (zone colors, category colors) - migrate to design tokens
C. Inline styling (color: '#fff') - replace with var(--xx-token)
Extends scripts/check-agent-docs-drift.sh to catch a second class of
agent-doc drift: per-tool subdirectory duplicates introduced by an
earlier 'centralize AI agent documentation references' refactor.
The refactor (visible in learning_ai_clock origin/main, commit c73fda7)
created .claude/AGENTS.md, .cline/AGENTS.md, .cursor/AGENTS.md as 1-line
redirect pointers, plus .devin/AGENTS.md (218 lines) and .devin/CONTEXT.md
(206 lines) with full duplicate documentation. All five duplicate the
canonical repo-root AGENTS.md.
The drift check now exits 1 if any of those five paths exist in any
repo listed in repos.txt. Also renumber comment markers (was 1..5,
now 1..6) and update the header comment.
Verified: bash scripts/check-agent-docs-drift.sh exits 0 with
'17 repos in sync' across the ecosystem.
The Gitea outdated-package detector reported @bytelyst/kill-switch-client
as the only @bytelyst/* package whose local content fingerprint differed
from the version already published to the registry. All other 63
packages in packages/ were UP-TO-DATE.
Publishing details:
Before: 0.1.5 (registry + local)
After: 0.1.6 (script auto-bumped patch + published)
Files: 9 (dist/index.* + package.json), 3.2 kB tarball,
shasum a9110243046f12be01b16f48f962ab64c0971d80
Target: http://localhost:3300/api/packages/bytelyst/npm/ (corp SSH tunnel)
Detected via:
bash scripts/gitea/publish-outdated-packages.sh --dry-run
-> Summary: 63 up-to-date, 1 changed, 1 skipped, 0 errors
Published via:
bash scripts/gitea/publish-outdated-packages.sh \
--skip-build \
--filter @bytelyst/kill-switch-client
-> + @bytelyst/kill-switch-client@0.1.6
Re-verification dry-run after publish:
-> Summary: 64 up-to-date, 0 changed, 1 skipped, 0 errors
-> 'All packages are up to date. Nothing to publish.'
This bump touches two files:
- packages/kill-switch-client/package.json (version 0.1.5 -> 0.1.6)
- scripts/gitea/.publish-manifest.json (content-hash bookkeeping
so future dry-runs don't re-flag this version as needing publish)
Used --skip-build because 'pnpm build' would have tried to build
services/platform-service, which currently has 3 unrelated TS errors
(missing @bytelyst/devops/server module + 2 ProductIdentity property
mismatches). Built only @bytelyst/* packages via
'pnpm --filter ./packages/** build' first (all 65 packages built
clean) and then ran the publisher with --skip-build.
Followup audit of the single-source-of-truth agent-docs rollout. Several
AI.dev prompts and skills still taught agents the old 8-file pattern (which
would re-introduce drift) and the generator script emitted a misleading
summary in --no-commit mode.
AI.dev guides:
- Delete AI.dev/SKILLS/update-agent-docs.md — entire doc taught the old
8-file pattern. Canonical reference is now
.windsurf/workflows/repo_update-agent-docs.md.
- AI.dev/SKILLS/index.md + README.md: replace dangling 'Update Agent
Documentation' link with pointers to agent-behavior-guidelines.md,
agent-onboarding.md, and the workflow doc.
- AI.dev/SKILLS/scan-repo-context.md: remove instructions to read
.windsurfrules / write .cursorrules. Point at the canonical behavior file.
- AI.dev/PROMPTS/new-product-scaffold.md: remove .windsurfrules and CLAUDE.md
from the scaffold tree. Add deprecated-files callout + regeneration hint.
- AI.dev/PROMPTS/agents-md-sync.md: drop 'Step 4 update CLAUDE.md', point at
the generator instead. Remove CLAUDE.md from `git add`.
- AI.dev/PROMPTS/ecosystem-audit.md: replace 'CLAUDE.md exists?' with
'canonical-behavior-pointer block present? legacy files absent?'.
Script UX:
- scripts/update-agent-docs.sh: stop printing 'All repos already in sync'
when --no-commit suppressed commits or --dry-run was used. Emit accurate
per-mode summaries instead.
Root causes found:
1. publishConfig.registry in each package.json overrides --registry CLI
flag, causing npm to hit gitea.bytelyst.com through corp proxy.
2. Global ~/.npmrc proxy settings (NPM_CONFIG_PROXY env vars) route
localhost:3300 through the corporate proxy.
3. No .npmrc with auth token was created for npm publish to use.
Fix: generate a proper .npmrc in WORK_DIR with:
- _authToken for registry auth
- @bytelyst:registry scoped override (bypasses publishConfig)
- proxy=false + https-proxy=false on corp network
- Unified corp/home publish path (both use same .npmrc)
Token scope issue still open: current GITEA_NPM_TOKEN has read:package
but not write:package — needs regeneration in Gitea UI.
- Use shared ~/.npmrc via --userconfig for all npm view + publish calls
(inline --// flags are unreliable on npm v10+ for writes)
- Verify registry credentials upfront before any work begins
- Log each package status inline as scan runs (✓/⊘/→/✗) grouped by workspace
- Suppress noisy npm notice / pnpm progress output; surface only errors
- Move FAILED to its own tracked array; exit non-zero if any publish fails
- Restrict release commits to package.json / pnpm-lock.yaml / .changeset
(prevents node-compile-cache and other generated dirs being committed)
- Fix pagination bug in registry comparison (was only checking 50 packages)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
