agentleFS
KarstenKrehKarstenKreh/Standby.Design/CLAUDE.md

Standby.Design

CLAUDE.md1 starsChanged 15 days agoMITView on GitHub

Operational knowledge for agents working in this repo. Architecture lives in CONTEXT.md, product strategy in STRATEGY.md — read those for the what; this file is the how-to-not-get-stuck. - The npm account uses passkey 2FA — there are no TOTP codes. npm's browser auth flow requires a real TTY; from an agent session shell, npm publish fails (EOTP) and masks the auth URL. Never try to publish from the session shell, and don't send the user to a terminal. Instead, open…

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every export generator lives once in packages/core/src/*-code-export.ts.

    line 66
  2. Very specific:

    Run npm install in packages/design-lint first.

    line 88
  3. Very specific:

    Verify MCP server changes with npm run smoke (end-to-end stdio test).

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Operational knowledge for agents working in this repo. Architecture lives in CONTEXT.md, product strategy in STRATEGY.md — read those for the what; this file is the how-to-not-get-stuck.

npm publish (standby-design-mcp, standby-design-lint)

  • The npm account uses passkey 2FA — there are no TOTP codes. npm's browser auth flow requires a real TTY; from an agent session shell, npm publish fails (EOTP) and masks the auth URL. Never try to publish from the session shell, and don't send the user to a terminal. Instead, open a visible window on the user's desktop:

    Start-Process powershell -ArgumentList '-NoExit','-Command','Set-Location "C:\Users\karst\repositories\Solopreneur\standby.design\packages\mcp-server"; npm publish'

    The browser opens, the user confirms the passkey. If they check "do not challenge for 5 minutes", follow-up publishes from the session shell work without a prompt — useful for quick re-publishes.

  • Version bump touches three places: package.json (version), src/server.ts (SERVER_VERSION), server.json (version and packages[0].version).
  • mcpName in package.json must stay io.github.KarstenKreh/standby-design-mcp — case-sensitive and must exactly match the name in server.json, or the MCP registry rejects the publish.
  • MCP registry update after an npm release: mcp-publisher login github (device flow, user confirms code) then mcp-publisher publish. Binary: GitHub releases of modelcontextprotocol/registry (mcp-publisher_windows_amd64.tar.gz). Registry description max 100 chars.
  • standby-design-lint is published the same way, with Set-Location on ...\packages\design-lint (first publish: npm publish --access public). Its version lives only in packages/design-lint/package.json; the plugin meta reads it from there. Publish it before deploying the site or the MCP server, both point to it.

Deploys (website + remote MCP server)

  • bash deploy.sh deploys everything (site + standby-mcp container for mcp.standby.design). SSH auth runs through the 1Password SSH agent — there is no key file on disk. The user may need to confirm a 1Password popup; if auth fails, check ssh-add -L and the whitelist in %LOCALAPPDATA%\1Password\config\ssh\agent.toml.
  • The script must use Windows OpenSSH (it prepends the PATH itself) — Git Bash's bundled ssh cannot reach the 1Password agent pipe.
  • Never pipe deploy.sh through tail/head in a background task. Those buffer until EOF, so the log stays empty for the whole run and the deploy looks hung when it is only building images on the server (several minutes, normal). Run it bare and read the output file as it grows. Before blaming SSH, verify with ssh -v -o BatchMode=yes -o ConnectTimeout=10 root@46.225.131.97 'echo ok' — that fails fast instead of waiting on a prompt.
  • New root-level static files (public/*.html, *.txt) also need a COPY line in the root Dockerfile, or they 404 in production while working locally.

Pitfalls

  • The design rules at /docs/rules and the research pages at /docs/research are generated. Edit docs/rules/*.md or docs/research/*.md, then run npm run build in docs/ and commit the output in public/docs/ (see docs/README.md).
  • Every export generator lives once in packages/core/src/*-code-export.ts. The System page and the MCP server compose them through packages/core/src/system-export.ts and resolve a hash with resolveDesignSystem (design-system.ts). Defaults per tool sit next to the codec in packages/core/src/url-state/*.ts. Rebuild the MCP server (packages/mcp-server: npm run build) after generator changes.
  • Each tool app syncs its store with the URL hash in src/lib/hash-sync.ts (startHashSync from @core/hash-sync), before the first render.
  • color-react has snapshot tests covering export output: review the diff first, then update with npx vitest run -u.
  • The apps build with vite build only (no type checking). Run npx tsc --noEmit where needed; packages/mcp-server has a proper typecheck script.
  • On Windows the docs build appends a second copy of every entry to public/sitemap.xml when the file has CRLF line endings. Convert it to LF before npm run build (sed -i 's/\r$//' public/sitemap.xml) and check that the diff only adds the new pages.
  • packages/design-lint enforces the design rules: a Claude Code hook (.claude/settings.json) lints every edited line, .githooks/pre-commit the staged lines and only warns (activate once with git config core.hooksPath .githooks), CI the lines of a PR and fails. Other projects get all of it with npx standby-design-lint@latest init. Run npm install in packages/design-lint first. Existing violations in the apps are known; they only show up when a line is touched.
  • Verify MCP server changes with npm run smoke (end-to-end stdio test); the remote variant serves /health for a quick liveness check.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.