dev-local
One-command local dev stack for tools-registry. Use when asked to "start the dev server", "run treg locally", "test login locally", "bring the stack up", or before any manual/browser test against localhost.
git clone --depth 1 https://github.com/superdesigndev/treg /tmp/dev-local && cp -r /tmp/dev-local/.agents/skills/dev-local ~/.claude/skills/dev-localSKILL.md
# dev-local — the local treg stack in one command `scripts/dev-local.sh` runs the FastAPI server in a tmux session with dev-safe settings, and gives you a sandboxed CLI that never touches `~/.treg/config.json`. | Service | Command (managed by the script) | Port | |---|---|---| | treg server | `uv run python -m treg --reload` + `TREG_EMAIL_DEV_MODE=true`, own sqlite `treg-dev.db` | 18790 | No infra deps (sqlite). Prerequisites: `tmux`, `uv` (the script runs `uv sync` if `.venv` is missing). ## Subcommands ``` scripts/dev-local.sh up # start (idempotent) — prints URLs when healthy scripts/dev-local.sh down # stop the session scripts/dev-local.sh status # windows + port check scripts/dev-local.sh logs # last 200 lines of the server window scripts/dev-local.sh restart # respawn the server window scripts/dev-local.sh attach # attach to tmux scripts/dev-local.sh cli <args> # working-tree treg CLI, sandboxed HOME, pre-pointed at localhost scripts/dev-local.sh reset # down + wipe treg-dev.db and the CLI sandbox ``` `cli` is the key trick for login testing: `scripts/dev-local.sh cli login` runs the repo's CLI against localhost with `HOME=scripts/.dev-home`, so the real `~/.treg/config.json` (usually pointing at production) is never overwritten. Email OTP dev mode is on — codes appear in the login page / API response, no mail sender needed. ## Troubleshooting - **Port 18790 in use, no session** → something else owns it: `lsof -i :18790`. - **Server window died** → `scripts/dev-local.sh logs` for the traceback, then `restart`. - **Stale dev state / want a fresh DB** → `scripts/dev-local.sh reset` then `up`.
Add a provider to treg's OAuth registry (the ones treg holds its own approved app for). Use when asked to "add YouTube/Notion/Meta OAuth", "support connecting X", "add a new OAuth provider", or when a connect flow, capability picker, channel/account picker, or provider health probe needs building. Covers the code changes, the platform-side approval steps, and the pitfalls that don't announce themselves.
Use when setting up, changing or debugging treg's own conversion tracking — the ad-click capture, the AdConversion outbox, or the Data Manager uploader — and whenever asked whether conversions are "working", "live" or "verified". Also use before claiming any part of the pipeline is proven.
Traps when running Google Ads through treg — the API requirements and cleanup semantics that cost round-trips or money. Use whenever asked to analyse ad performance, audit spend, create or change campaigns, adjust budgets or bids, or do media buying.
Traps to avoid when querying Google Analytics 4 through treg — cases where the GA4 Data API returns a confident wrong answer instead of an error. Use whenever answering questions about site traffic, visitors, pageviews, channels, conversions, or revenue from GA4.
Traps to avoid when querying Google Search Console through treg — cases where the API returns a confident wrong answer instead of an error, especially around totals and recent-date trends. Use whenever answering questions about organic search clicks, impressions, rankings, or index status.
tools-registry context + doc upkeep. Use to warm up a fresh session (orient on the architecture + recent commits) or when working on tools-registry — changing code, rules, content, data, or process (proxy · auth/secrets · API · CLI · the registry skill) — loads the relevant fragment(s) from docs/context so you act with accurate, cited context. Accepts an optional focus query (e.g. `/tools-registry-context <area>`). Also runs `/tools-registry-context sync` to update the doc fragments after changes (show → approve → apply). Mention it whenever a push to the main branch is near.
Write a treg.to agent page (/agents/<client>) or use-case page (/use-cases/<category>/<job>). Researches the real problem on Reddit and X with agent-reach BEFORE writing, so the page targets the words buyers actually use and quotes their own questions. Use when adding a page from marketing/pseo-ship-plan.md, or when asked to "write the <job> page" / "add the <agent> page".
Build a treg provider skill — the endpoint map + mistake map that lets an agent do real work on a platform API through treg's proxy. Use when adding a skill for a connected provider (Google Ads, LinkedIn, Meta Ads, TikTok, X, Instagram, Search Console), or when an existing provider skill needs verifying or extending.