# oyware kit

> Step-by-step workflows, Claude Code skills and reference notes for taking a web app from an empty VPS to a live, hardened, backed-up site. Every file uses placeholders defined in 00-setup-profile.md; ask the user for those values first.

Each workflow is Goal -> Inputs -> Steps (each ends with a Check) -> Traps -> Done when. Run the Check after every step; if it fails, read Traps before improvising.

## Start here

- [Setup profile](https://docs.oyware.com/kit/00-setup-profile.md): The placeholders every file in this kit uses. Fill them in once and give them to your AI.

## Workflows

- [Agent pipeline — tickets in, pull requests out](https://docs.oyware.com/kit/workflows/agent-pipeline.md): Turn issue-tracker tickets into Claude Code sessions on your own machine (Linear free plan + self-hosted Cyrus), with a per-repo rule for how far the agent may go
- [Backups and restore — nightly dumps, an off-machine copy, and a drill that proves them](https://docs.oyware.com/kit/workflows/backups-and-restore.md): Verified nightly pg_dump on the server, a pull to a second machine that survives sleep, and a scheduled restore into a scratch database that compares every table with live.
- [Browser flow tests that find real bugs](https://docs.oyware.com/kit/workflows/browser-flow-testing.md): Drive headless Chrome over the DevTools Protocol at phone width as a throwaway user, and after every action compare the screen with the API, then reload and compare again.
- [Design first — directions before code](https://docs.oyware.com/kit/workflows/design-first.md): Get several real design directions from an AI design tool (e.g. Claude Design), pick one, turn it into tokens, then build it screen by screen
- [Transactional email from a VPS that blocks SMTP](https://docs.oyware.com/kit/workflows/email-sending.md): Send password codes and notifications through an HTTPS email API, from an authenticated domain, and prove delivery from the provider's events rather than your own logs.
- [Lean production — run several Node apps on a 1 GB server](https://docs.oyware.com/kit/workflows/lean-production.md): Production builds only, a heap cap and a hard memory ceiling per app, builds on the laptop, leak-proof habits, and a memory reading after every deploy.
- [New server — from nothing to a hardened Ubuntu droplet](https://docs.oyware.com/kit/workflows/new-server.md): Domain, VPS, locked-down SSH, firewall, swap, Postgres on loopback, Nginx behind Cloudflare with an origin certificate, security headers and scanner filtering.
- [New web app — the default greenfield path](https://docs.oyware.com/kit/workflows/new-web-app.md): From an idea to a live, installable, tested web app on your own server — stack, repo layout, auth, tests, CLAUDE.md, deploy, portfolio
- [Parallel coding agents on one machine](https://docs.oyware.com/kit/workflows/parallel-agents.md): Run several coding agents at once without them colliding: a worktree, a test database, dev ports and a profile dir each, then review, merge one at a time and run every flow
- [Password reset by emailed code](https://docs.oyware.com/kit/workflows/password-reset.md): A "forgot password" flow that works inside installed PWAs — a six-digit code typed back into the app, hashed, rate-limited, enumeration-proof, ending every old session.
- [Installable PWA, service worker, and CDN cache rules](https://docs.oyware.com/kit/workflows/pwa-and-caching.md): Make an app installable and offline-tolerant without ever hiding a deploy, and set cache headers so neither the browser, the service worker nor Cloudflare serves something stale — or something private.
- [Ship a site — put a static site or a Node app live on your own server](https://docs.oyware.com/kit/workflows/ship-a-site.md): DNS record, Nginx server block, TLS, systemd service, a one-command deploy script that builds locally and fails closed, and verification from outside.

## Skills

- [Skill: add-password-reset](https://docs.oyware.com/kit/skills/add-password-reset/SKILL.md): Use when a web app has email + password login but no way back in — adding "forgot password", a reset flow, or letting someone who cannot log in prove they own their email address. Also use when choosing how a reset is delivered, when an existing reset leaves the user logged out in the wrong browser (installed PWA vs Safari), 404s on the reset screen, reveals which addresses have accounts, or never reaches the inbox.
- [Skill: agent-pipeline](https://docs.oyware.com/kit/skills/agent-pipeline/SKILL.md): Operate a ticket-to-agent pipeline — Linear (free plan) + self-hosted Cyrus running Claude Code on your own machine. Use when creating or updating tickets, handing a ticket to the agent, checking why a ticket did not start, reading the runner's status or logs, adding a repo to the pipeline, changing routing, or any Linear admin change. Also when the user says "make a ticket", "give it to the agent", "is the agent working", "add my repo".
- [Skill: browser-flows](https://docs.oyware.com/kit/skills/browser-flows/SKILL.md): Use when asked to test a web app, find bugs, verify a fix or a deploy in a real browser, or when a bug report says "I tapped X and the screen didn't change". Drives headless Chrome over the DevTools Protocol at phone width as a throwaway user, comparing the DOM with the API after every action and again after a reload. Also use when writing a regression test for a UI bug that unit tests cannot reach.
- [Skill: design-first](https://docs.oyware.com/kit/skills/design-first/SKILL.md): Get real design directions from an AI design tool (Claude Design or similar) before building UI. Gather real screenshots and features, write a brief that forbids invented content, run one generation at a time, export the HTML, render every artboard to PNG, review, then hand DESIGN.md + artboards to builders. Use when the user says "design it first", "get options from Claude Design", wants landing pages, app screens, UI states or a redesign, or wants several directions to choose from. Not for building the code itself.
- [Skill: ship-a-site](https://docs.oyware.com/kit/skills/ship-a-site/SKILL.md): Put a website, single-page app or Node API live on your own Linux server (VPS/droplet) behind Cloudflare — DNS record, Nginx server block, TLS with an origin certificate, a capped systemd service, a one-command deploy script, backups and a restore drill — or build a brand-new hardened server from scratch. Use whenever the user wants to ship, publish, deploy, self-host or put something online; add a subdomain; move off Vercel/Netlify/Render/Heroku to a VPS; set up a server for a client; or when a self-hosted site is broken (502, certificate errors, service not starting, stale files after a deploy, security headers missing, memory climbing).

## Reference

- [Gotchas — server, deploy and CDN traps, as symptom → cause → fix](https://docs.oyware.com/kit/reference/gotchas.md): Every infrastructure failure mode met while running several apps on one small Ubuntu server behind Cloudflare. Most are silent.
- [Default stack](https://docs.oyware.com/kit/reference/stack.md): The stack every app here starts from, the versions actually in use, and why each piece was chosen
- [Working with AI coding agents](https://docs.oyware.com/kit/reference/working-with-ai.md): The lessons that decided whether an AI agent's work could be trusted: verify with real flows, measure, don't invent, state costs, capture repeated work as skills
- [CLAUDE.md](https://docs.oyware.com/kit/reference/CLAUDE.md.template): <One sentence: what it is and who uses it.> Live at https://<app>.<domain>.

## Optional

- [README](https://docs.oyware.com/kit/README.md): what the kit is and how to use it
- [Source repository](https://github.com/OmarYousef95/oyware-kit): clone it, or copy skills/ into ~/.claude/skills/