@refactco/refact-os 1.5.0

package/templates/overlays/code/agent/skills/add-codebase/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: add-codebase
+description: Clone or scaffold an external codebase into apps/<slot>/, stripping .git so it merges into the parent repo.
+pattern: procedure
+when_to_use: /refact add codebase <url | wordpress | seo | api | mobile>.
+when_not_to_use: Editing code already under apps/ (use code-development).
+next_skills: []
+sub_agents: []
+---
+
+# Add Codebase Reference
+
+Use this reference when the user invokes `/refact add codebase ...` (or similar phrasings: "drop the client repo into apps", "scaffold a new WordPress codebase", "add a plugin to the WP app", etc.).
+
+## Goal
+
+Manage the `apps/` directory: import existing GitHub repos as **vendored snapshots**, or scaffold fresh app slots.
+
+`apps/` is tracked as part of this engagement repo. Imported clones have their `.git` directory stripped on entry, so each slot merges cleanly into the parent's git history with no nested repos or submodule confusion. Once placed, edit files in `apps/<slot>/` like any other source — there is no separate upstream to push back to from here.
+
+## Argument shapes
+
+| User input | Flow | Where it lands |
+|---|---|---|
+| `<git-url>` (https or ssh) | **Flow A** — clone, detect, place, deref | `apps/<slot>/` |
+| `wordpress` | **Flow B** — fresh WP scaffold | `apps/wordpress/` |
+| `seo`, `api`, `mobile` | **Flow C** — empty slot | `apps/<slot>/` |
+
+If the user passes anything else (e.g. `nextjs`, `front-end`, `wordpress plugin`), ask one focused clarifying question — these are not part of the supported set yet, so do **not** invent a scaffold.
+
+## Preflight (always)
+
+1. Confirm we are inside a refact-os scaffold:
+   - `agent/AGENTS.md` exists at the project root, AND
+   - `.cursor/` directory exists.
+   If not, stop and tell the user to run the scaffolder first (`npx refact-os init`).
+2. Ensure the `apps/` directory exists at the project root. Create it if missing.
+
+---
+
+## Flow A — URL clone
+
+Triggered when the argument looks like a URL: starts with `http://`, `https://`, `git@`, or `ssh://`, or matches `<owner>/<repo>` shorthand (in which case expand to `https://github.com/<owner>/<repo>`).
+
+### A1. Clone to a staging directory first
+
+Do **not** clone directly into `apps/<slot>/` — we need to inspect the contents before placing them. Use a staging dir under `apps/.staging-<rand>/`:
+
+```bash
+STAGING="apps/.staging-$(date +%s)-$$"
+git clone --no-tags "<url>" "$STAGING"
+```
+
+If the clone fails (auth, network, repo moved), surface the exact error and stop. Do **not** retry by swapping protocols.
+
+### A2. Capture provenance BEFORE stripping .git
+
+While the `.git` is still present, capture origin URL, HEAD SHA, default branch, and recent history into a single breadcrumb file:
+
+```bash
+ORIGIN_URL="$(git -C "$STAGING" remote get-url origin)"
+HEAD_SHA="$(git -C "$STAGING" rev-parse HEAD)"
+DEFAULT_BRANCH="$(git -C "$STAGING" symbolic-ref --short HEAD 2>/dev/null || echo 'detached')"
+RECENT_LOG="$(git -C "$STAGING" log --oneline -n 50 2>/dev/null || echo '(no history available)')"
+IMPORT_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+```
+
+You will write these into `apps/<slot>/REFACT-SOURCE.md` in step A5.
+
+### A3. Detect the codebase type
+
+Run these checks inside `$STAGING` in order; stop at the first match:
+
+| Indicator | Suggested slot | Notes |
+|---|---|---|
+| Root has `wp-config.php` or `wp-config-sample.php` or `wp-load.php` | `wordpress` | Full WP core checkout |
+| Root has `wp-content/` directory | `wordpress` | wp-content-only or full |
+| Root has `.wp-env.json` and `wp-content/` mapped | `wordpress` | Refact-style WP project |
+| Root has `composer.json` referencing `roots/bedrock` or `johnpbloch/wordpress-core` | `wordpress` | Bedrock-style |
+| Root has a `*.php` file with `Plugin Name:` header line | **stop — single plugin** | See A3.1 |
+| Root has `style.css` with `Theme Name:` header line | **stop — single theme** | See A3.2 |
+| Root has `next.config.*` or `package.json` with `next` dependency | `front-end` | Next.js |
+| Root has `package.json` with `react` dep (no Next) or `vite.config.*` | `front-end` | Generic React / Vite |
+| Root has `package.json` with `expo` or `react-native` dep | `mobile` | |
+| Root has `Cargo.toml`, `go.mod`, `pyproject.toml` only | `api` | Backend / service |
+| None of the above | (ask the user) | See A3.3 |
+
+#### A3.1 Single plugin
+
+If detection identifies a single WordPress plugin (root `*.php` with `Plugin Name:` header and no `wp-content/`), stop and tell the user:
+
+> "This URL looks like a single WordPress plugin, not a full codebase. Run `/refact add codebase wordpress` first to set up `apps/wordpress/`, then re-add this URL — I'll place it under `wp-content/plugins/<repo-name>/`."
+
+Do **not** proceed. Remove the staging dir (`rm -rf "$STAGING"`).
+
+If `apps/wordpress/` **already exists**, you may offer to place the plugin under `apps/wordpress/wp-content/plugins/<repo-name>/` directly — but ask before doing so.
+
+#### A3.2 Single theme
+
+Same shape as A3.1, but for themes. The destination would be `apps/wordpress/wp-content/themes/<repo-name>/`.
+
+#### A3.3 Ambiguous
+
+If no indicator matches, ask the user one question:
+
+> "I couldn't auto-detect the type of this codebase. What slot name should I use under `apps/`? Common: `wordpress`, `front-end`, `seo`, `api`, `mobile`. Anything else works too."
+
+Accept any slug (kebab-case, ASCII letters/digits/hyphens).
+
+### A4. Confirm the slot with the user
+
+Even when detection succeeds, propose the slot and let the user override:
+
+> "Detected: WordPress codebase. I'll place it at `apps/wordpress/`. OK, or different slot name?"
+
+The vocabulary is **not fixed** — detection suggests, the user decides. Validate the final slot name is kebab-case ASCII (no spaces, no `/`, no `..`).
+
+### A5. Conflict guard
+
+If `apps/<slot>/` already exists AND is non-empty, **stop** with:
+
+> "An `apps/<slot>/` codebase already exists. Refusing to overwrite. To replace it, remove `apps/<slot>/` manually first, then re-run this command."
+
+Clean up the staging dir (`rm -rf "$STAGING"`) before surfacing the error.
+
+### A6. Move staging → slot, strip .git, write breadcrumb
+
+```bash
+mv "$STAGING" "apps/<slot>"
+rm -rf "apps/<slot>/.git"
+```
+
+Then write `apps/<slot>/REFACT-SOURCE.md` with the values captured in A2:
+
+```markdown
+# Source
+
+This codebase was imported via `/refact add codebase` on <IMPORT_DATE>.
+
+- **Origin:** <ORIGIN_URL>
+- **HEAD at import:** <HEAD_SHA>
+- **Default branch:** <DEFAULT_BRANCH>
+
+The original `.git` directory has been removed — this is a vendored, reference-only snapshot. Do **not** commit, push, or treat this as a live clone.
+
+## Recent history (at time of import)
+
+```
+<RECENT_LOG>
+```
+```
+
+### A7. Report
+
+Tell the user:
+- The slot path (`apps/<slot>/`)
+- The origin URL and HEAD SHA
+- That `.git` was removed and a breadcrumb was written
+- That this is reference-only — to make changes upstream, work in a separate clone
+
+---
+
+## Flow B — Fresh WordPress scaffold
+
+Triggered by `/refact add codebase wordpress` (with no further argument).
+
+### B1. Conflict guard
+
+If `apps/wordpress/` already exists, **stop** with:
+
+> "An `apps/wordpress/` codebase already exists. Refusing to overwrite. Remove `apps/wordpress/` manually first to start over."
+
+### B2. Create skeleton
+
+```bash
+mkdir -p apps/wordpress/wp-content/plugins
+mkdir -p apps/wordpress/wp-content/themes
+mkdir -p apps/wordpress/wp-content/mu-plugins
+touch apps/wordpress/wp-content/plugins/.gitkeep
+touch apps/wordpress/wp-content/themes/.gitkeep
+touch apps/wordpress/wp-content/mu-plugins/.gitkeep
+```
+
+### B3. Write a stub README
+
+Write `apps/wordpress/REFACT-SOURCE.md`:
+
+```markdown
+# Source
+
+Created fresh via `/refact add codebase wordpress` on <DATE>.
+
+This slot is an empty WordPress codebase shell. Drop the client's WordPress source here — plugins under `wp-content/plugins/`, themes under `wp-content/themes/`, mu-plugins under `wp-content/mu-plugins/`.
+```
+
+### B4. Report
+
+Tell the user the slot exists with empty `wp-content/{plugins,themes,mu-plugins}/` ready for content.
+
+---
+
+## Flow C — Fresh empty slot (`seo` / `api` / `mobile`)
+
+Triggered by `/refact add codebase {seo|api|mobile}`.
+
+### C1. Conflict guard
+
+If `apps/<slot>/` already exists, **stop** with the same per-slot refusal message used in A5.
+
+### C2. Create skeleton
+
+```bash
+mkdir -p apps/<slot>
+```
+
+Write `apps/<slot>/REFACT-SOURCE.md`:
+
+```markdown
+# Source
+
+Created fresh via `/refact add codebase <slot>` on <DATE>.
+
+This slot is a vendored, reference-only placeholder. Drop a related codebase here, or use `/refact add codebase <url>` to import an existing repo into this slot.
+```
+
+### C3. Report
+
+Tell the user the slot exists and is empty, ready for content.
+
+---
+
+## Guardrails
+
+- **Commits to `apps/*` go to the parent engagement repo, not to any upstream.** Imported clones have `.git` removed precisely so there's no path back to the original remote. If the user wants changes upstreamed, they need a separate clone for that.
+- **Never** overwrite an existing slot. Always refuse and ask the user to remove it manually first.
+- **Never** invent a scaffold for an unsupported keyword. Ask the user instead.
+- **Never** silently rename the slot if detection is ambiguous. Always confirm with the user before placing files.
+- **Never** skip the `REFACT-SOURCE.md` breadcrumb after a URL clone — it's the only paper trail of where the code came from.
+- If a clone or scaffold fails partway, clean up the partial slot (`rm -rf apps/<slot>`) before surfacing the error so a retry doesn't trip the conflict guard.

package/templates/overlays/code/agent/skills/code-development/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: code-development
+description: Use whenever the user asks to add a feature, fix a bug, refactor code, or otherwise change committed code in this project. Enforces the team's branching/PR workflow (GitFlow) before any edits begin, and routes to other code-development references as needed.
+pattern: procedure
+when_to_use: Any task that will result in committed code changes — "add a feature", "fix the bug", "refactor", "update the styling", "wire up the endpoint".
+when_not_to_use: Read-only questions, exploration, documentation lookups, or chat/transcript processing (those go through /refact).
+next_skills: []
+sub_agents: []
+---
+
+# Code Development Skill
+
+This skill is the gate every code change passes through. Before editing files, it makes sure the agent is on the right branch and following the team's GitFlow.
+
+## When to invoke
+
+Invoke this skill at the **start** of any task that will result in committed code changes:
+
+- "Add a feature…"
+- "Fix the bug where…"
+- "Refactor the …"
+- "Update the styling of…"
+- "Wire up the new endpoint…"
+- Any user message that implies an edit to versioned files.
+
+Do **not** invoke for: read-only questions, exploration, documentation lookups, or chat history / transcript processing (those go through `/refact`).
+
+## Protocol
+
+For every development task, in order:
+
+1. **Consult `agent/skills/code-development/references/gitflow.md`** before touching any file. Run the preflight checks (clean working tree, current branch, remote present), sync the base branch, and create a properly named feature branch. If preflight fails, stop and report rather than working on the wrong branch.
+2. **Do the work** on the feature branch. Make focused commits with Conventional Commits messages (see the gitflow reference).
+3. **Push and open a PR into the base branch** (`staging` unless the project's `agent/AGENTS.md` says otherwise). Use the PR body template in `gitflow.md`.
+4. **Report the PR URL** and surface CI status to the user.
+
+## References
+
+| Topic | Reference |
+|---|---|
+| Branching, commits, PR workflow | `agent/skills/code-development/references/gitflow.md` |
+
+Add more references here as the project grows (testing conventions, code style, deploy process, …). Each new reference becomes another step the skill can route to.
+
+## Hard rules
+
+- Never edit committed files while still on the base branch (`staging` / `main`). Create the feature branch first.
+- Never open a PR into `main` unless the user explicitly requests a `staging → main` promotion.
+- Never bypass the gitflow reference "just for a small change." Small changes still need a branch and a PR.
+- If the project's actual base branch is not `staging`, ask the user once, update `agent/AGENTS.md`, and continue with the corrected name.
+
+## When unsure
+
+Ask one focused clarifying question rather than guessing on:
+
+- Whether a ticket ID exists for the work.
+- The intended scope of the change (one branch vs. several).
+- Whether the user wants the PR opened immediately or held as a draft.

package/templates/overlays/code/agent/skills/code-development/references/gitflow.md

@@ -0,0 +1,144 @@
+# GitFlow Reference
+
+The team's branching workflow. The `code-development` skill consults this **before** any edit that adds a feature, fixes a bug, or otherwise changes committed code. Read it once at the start of a development task and follow it end-to-end.
+
+## TL;DR
+
+```
+staging  ──●──────────●────────●──   (integration branch — never commit directly)
+            \         /\       /
+             \       /  \     /
+              feat/x      fix/y       (your work happens here)
+```
+
+1. Start from a clean, up-to-date `staging`.
+2. Cut a feature branch: `feat/<ticket>-<slug>`, `fix/<ticket>-<slug>`, or `chore/<slug>`.
+3. Commit in small, conventional-commit-style chunks.
+4. Push and open a PR **into `staging`** (never into `main`).
+5. Stop and surface CI failures / review feedback rather than force-pushing past them.
+
+## Hard rules
+
+1. **Never commit or push directly to `staging` or `main`.** Both are protected integration branches. If you find yourself on one with uncommitted changes, stash them, switch to a feature branch, then pop the stash.
+2. **Never open a PR into `main`** unless the user has explicitly asked for a `staging → main` promotion. Default PR target is always `staging`.
+3. **Never force-push** (`--force`, `--force-with-lease`) without explicit user permission. If the remote rejects a push, stop and surface the error.
+4. **Never `git reset --hard`, `git clean -fd`, or delete branches** without confirming with the user — these destroy work.
+5. **Never skip hooks** (`--no-verify`, `--no-gpg-sign`). If a pre-commit hook fails, fix the underlying issue and re-commit.
+6. **Never amend a commit that has already been pushed** to a shared branch — create a new commit instead.
+
+## Step 1 — Preflight
+
+Before touching files, confirm the starting state:
+
+```bash
+git status                    # working tree should be clean
+git rev-parse --abbrev-ref HEAD   # what branch am I on?
+git remote -v                 # confirm origin exists
+```
+
+If the working tree is dirty with unrelated changes, stop and ask the user how to proceed (stash, commit elsewhere, discard). Do **not** sweep their in-progress work into your feature commit.
+
+## Step 2 — Sync `staging`
+
+```bash
+git fetch origin
+git switch staging
+git pull --ff-only origin staging
+```
+
+If `--ff-only` fails, `staging` has diverged locally — stop and ask the user how to reconcile rather than merging or rebasing autonomously.
+
+## Step 3 — Create the feature branch
+
+### Branch naming
+
+| Kind | Pattern | Example |
+|---|---|---|
+| New feature | `feat/<ticket>-<slug>` | `feat/ABC-123-testimonial-carousel` |
+| Bug fix | `fix/<ticket>-<slug>` | `fix/ABC-456-checkout-total` |
+| Maintenance, deps, tooling | `chore/<slug>` | `chore/upgrade-phpcs` |
+| Docs only | `docs/<slug>` | `docs/onboarding-guide` |
+
+Rules:
+
+- `<ticket>` is the issue / Asana / Linear ID when one exists. If there is no ticket, ask the user before omitting it — sometimes one needs to be created first.
+- `<slug>` is lowercase kebab-case, ≤ 5 words, describing the change.
+- One branch per logical change. If scope expands mid-flight, stop and ask whether to split.
+
+### Create and switch
+
+```bash
+git switch -c feat/<ticket>-<slug>
+```
+
+## Step 4 — Develop and commit
+
+### Commit style: Conventional Commits
+
+```
+<type>(<scope>): <subject>
+
+<optional body — the *why*, links to ticket, anything non-obvious>
+```
+
+- **Types:** `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `perf`, `build`, `ci`, `style`.
+- **Subject:** imperative mood, no trailing period, ≤ 72 chars.
+- **Scope:** short module name (e.g. `feat(blocks): …`, `fix(checkout): …`). Omit if it doesn't fit.
+
+### Commit hygiene
+
+- Stage files explicitly (`git add path/to/file`) — avoid `git add -A` / `git add .` so secrets, generated files, and unrelated edits don't sneak in.
+- Run the project's test / lint / build commands locally before pushing. CI must be green before review.
+- Keep commits focused — one logical change per commit makes review and revert easier.
+
+## Step 5 — Push
+
+```bash
+git push -u origin feat/<ticket>-<slug>
+```
+
+If the remote already has a branch with the same name that you didn't create, stop and ask the user.
+
+## Step 6 — Open the PR
+
+```bash
+gh pr create --base staging --head feat/<ticket>-<slug> \
+  --title "<conventional-commit-style title>" \
+  --body  "<see body template below>"
+```
+
+PR body template:
+
+```markdown
+## Summary
+- <1–3 bullets — what changed>
+
+## Why
+- <link the ticket; explain the motivation if non-obvious>
+
+## Test plan
+- [ ] <how a reviewer can verify locally>
+- [ ] <screenshots / Loom for visual or admin changes>
+
+## Notes
+- <migrations, follow-ups, anything reviewers should know>
+```
+
+After opening:
+
+- Report the PR URL back to the user.
+- If CI fails, surface the failing job output — do not silently re-run or rewrite history to mask the failure.
+
+## Step 7 — Respond to review
+
+- Push new commits to address feedback; don't squash or rebase a pushed branch without asking.
+- When the PR is approved and merged, the feature branch can be deleted on GitHub. Delete the local branch with `git branch -d <name>` (use `-d`, not `-D`, so git refuses if anything is unmerged).
+
+## When to stop and ask the user
+
+- The base branch isn't actually called `staging` (the repo uses `develop`, `dev`, `trunk`, etc.). Confirm before proceeding.
+- The working tree starts dirty with unrelated changes.
+- A pull / push / merge fails for any reason.
+- The scope of the change grows beyond what the original branch name implies.
+- You're about to do anything destructive (`reset --hard`, `clean -fd`, branch deletion, force push).
+- The task seems to require committing to `staging` or `main` directly — there is almost always a better path.

package/templates/overlays/nextjs/agent/skills/nextjs-dev/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: nextjs-dev
+description: Work safely inside an existing Next.js app: locate the app, run dev/build/lint checks, and diagnose common App Router issues.
+pattern: procedure
+when_to_use: /refact nextjs dev | run the Next.js app | fix Next.js bug | update a Next.js route, component, server action, or API endpoint.
+when_not_to_use: Creating or adopting a new app (use setup-nextjs-app), or deployment setup (use setup-vercel-deploy).
+next_skills: []
+sub_agents: []
+---
+
+# Next.js Development Reference
+
+Use this reference for day-to-day development work in an existing Next.js app.
+
+## Goal
+
+Keep agents grounded in the target app's actual conventions: App Router versus Pages Router, package manager, component library, environment variables, and available checks.
+
+## Preflight
+
+1. Identify the target app:
+   - If the user named a path, use it.
+   - Otherwise look for `apps/*/next.config.*` or `apps/*/package.json` with a `next` dependency.
+   - If multiple apps match, ask which one to use.
+2. Read the app's local `AGENTS.md` if present, then the root `agent/AGENTS.md`.
+3. Detect package manager from lockfiles, preferring the closest lockfile to the app.
+4. Read `package.json` scripts before running commands. Do not assume `lint`, `typecheck`, `test`, or `build` exists.
+5. Check for framework shape:
+   - `app/` or `src/app/` means App Router.
+   - `pages/` or `src/pages/` means Pages Router.
+   - Mixed router apps require extra care; preserve the existing boundary.
+
+## Development flow
+
+1. Reproduce or understand the requested behavior before editing when practical.
+2. Make the smallest app-local change that fits the existing structure.
+3. Preserve server/client boundaries:
+   - Add `"use client"` only when the component needs browser-only state, effects, event handlers, or client APIs.
+   - Keep data fetching, secrets, filesystem access, and privileged SDK calls server-side.
+   - Do not pass non-serializable values from Server Components into Client Components.
+4. Keep route handlers and Server Actions explicit about runtime assumptions. Do not move code to Edge runtime unless the dependencies are Edge-safe.
+5. Use the project's existing styling system. Do not introduce Tailwind, shadcn/ui, CSS-in-JS, or a component library unless the project already uses it or the user asks.
+6. If environment variables are needed, update `.env.example` or docs with names only. Never write real secret values.
+
+## Common checks
+
+Run the smallest relevant checks available in `package.json`:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+Use the actual package manager. For narrowly scoped component edits, lint/typecheck may be enough. For routing, metadata, server actions, middleware/proxy, or config changes, prefer a production build if available.
+
+## Local dev server
+
+Before starting a dev server:
+
+1. Check whether one is already running in the IDE terminals.
+2. Use the app's existing dev script.
+3. If the default port is occupied, surface the conflict and ask before changing ports.
+
+Typical command:
+
+```bash
+npm run dev
+```
+
+## Debugging checklist
+
+- Hydration mismatch: check time/random values, browser-only APIs, conditional rendering by viewport, and inconsistent server/client data.
+- Server/Client Component error: remove unnecessary `"use client"` or split the interactive leaf into a client component.
+- Route not found: verify segment folder names, dynamic segment syntax, route groups, parallel routes, and whether the app uses `src/`.
+- Metadata issue: check `metadata`, `generateMetadata`, and whether the route is static or dynamic.
+- API/route handler issue: check method exports, returned `Response`, runtime dependencies, and auth/env availability.
+- Build-only failure: run the production build and fix the first real error rather than chasing dev overlay noise.
+
+## Guardrails
+
+- Never commit `.env*` files with real values.
+- Never disable TypeScript, ESLint, auth, or validation to make a build pass.
+- Never add `"use client"` at a high layout boundary without a reason; it can pull too much of the tree client-side.
+- Never edit generated framework output (`.next/`, `out/`, coverage, cache folders).
+- Never assume Vercel deployment unless `vercel.json`, `.vercel/`, project docs, or the user says so.
+
+## When to stop and ask
+
+- Multiple matching apps exist and the user did not name one.
+- A fix requires changing the routing strategy, auth provider, database client, or deployment runtime.
+- Existing checks are absent or failing before your change and the failure affects confidence in the work.

package/templates/overlays/nextjs/agent/skills/setup-netlify-deploy/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: setup-netlify-deploy
+description: Link a Next.js app to Netlify and document deployment settings without assuming every Next.js project deploys to Netlify.
+pattern: procedure
+requires_approval: true
+when_to_use: /refact setup netlify deploy | deploy Next.js to Netlify | link this Next.js app to Netlify | configure Netlify for this app.
+when_not_to_use: Non-Netlify hosting, local-only development, or generic Next.js code changes.
+next_skills:
+  - nextjs-dev
+sub_agents: []
+---
+
+# Netlify Deploy Setup Reference
+
+Use this reference when the user explicitly wants a Next.js app linked or configured for Netlify. Do not run this automatically for every Next.js project.
+
+## Goal
+
+Set up Netlify deployment metadata and verification while keeping hosting choices explicit. This skill may call external services, create project links, and change deploy settings, so it requires user approval before writes.
+
+## Preflight
+
+1. Confirm the target app path. If multiple Next.js apps exist, ask which app to deploy.
+2. Confirm Netlify is the intended hosting provider.
+3. Check whether the Netlify CLI exists:
+
+   ```bash
+   netlify --version
+   ```
+
+   If missing, ask before installing it. Prefer `npx netlify-cli` for one-off setup unless the user wants a global CLI.
+
+4. Check authentication:
+
+   ```bash
+   netlify status
+   ```
+
+   If unauthenticated, stop and ask the user to run `netlify login`. Do not handle credentials or tokens in chat.
+
+5. Inspect existing Netlify state:
+   - `.netlify/state.json` means the app or repo may already be linked.
+   - `netlify.toml` may define build base, command, publish directory, redirects, headers, functions, or plugins.
+   - Existing GitHub workflows may already deploy the app.
+
+## Link flow
+
+1. From the target app directory, run one of:
+
+   ```bash
+   netlify init
+   netlify link
+   ```
+
+   Use `init` for a new Netlify site and `link` for an existing Netlify site.
+
+2. If the repo is a monorepo, make sure Netlify's base directory points at the app directory (`apps/<app-name>`) unless the repo intentionally builds from root.
+3. Do not commit `.netlify/` unless the team intentionally tracks Netlify project metadata. If unsure, ask. Many teams keep it local and document the site name/id instead.
+4. Record hosting (`netlify`) and each environment's `branch` + `url` (production and staging) in `.refact-os.json` › `stack.nextjs` when stable. Keep app-specific build details (team, site name, app root, build command, publish directory) in `apps/<app-name>/docs/deploy.md`.
+
+## Build settings
+
+Prefer Netlify's Next.js detection when it works. Only add or edit `netlify.toml` when the repo needs explicit settings, such as a monorepo app root or custom redirects.
+
+Typical app-local settings when `netlify.toml` lives inside `apps/<app-name>/`:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = ".next"
+```
+
+Typical root-level monorepo settings:
+
+```toml
+[build]
+  base = "apps/<app-name>"
+  command = "npm run build"
+  publish = "apps/<app-name>/.next"
+```
+
+Use the actual package manager command. If the project already has a `netlify.toml`, read it first and preserve unrelated settings.
+
+## Environment variables
+
+1. List required variable names from docs, `.env.example`, and code references.
+2. Inspect Netlify env var names only with explicit user approval:
+
+   ```bash
+   netlify env:list
+   ```
+
+3. Never paste secret values into files, chat, logs, or docs. Document names and purpose only.
+4. Keep local `.env.local` uncommitted.
+
+## Verification
+
+Prefer local production checks before deploying:
+
+```bash
+npm run build
+netlify build
+```
+
+Use the app's actual package manager. If `netlify build` fails because the project is not linked or env vars are missing, surface the missing piece rather than guessing.
+
+For a draft deploy, confirm with the user, then run:
+
+```bash
+netlify deploy
+```
+
+For production promotion, require explicit approval:
+
+```bash
+netlify deploy --prod
+```
+
+## Git integration
+
+If Netlify Git integration is enabled, prefer PR/branch deploys over ad-hoc CLI production deploys. Document:
+
+- Production branch.
+- Branch deploy behavior.
+- Deploy previews.
+- Monorepo base directory.
+- Required Netlify environment variables.
+
+## Guardrails
+
+- Never assume Netlify just because the app is Next.js.
+- Never deploy to production without explicit user approval.
+- Never print, commit, or store secret values.
+- Never change DNS, domains, production branch, build image, or team ownership without confirmation.
+- Never overwrite existing `netlify.toml` or CI workflows without reading them and explaining the change.
+- Never add Next.js runtime/plugin config blindly; use the current project settings and Netlify detection unless a build error proves explicit config is needed.
+
+## When to stop and ask
+
+- The app is already linked to a different Netlify site than the user named.
+- The repo root and Netlify base directory disagree.
+- Required environment variables are unknown or missing.
+- The user asks to promote a deploy to production or change domain settings.