cogni-dao/cogni / .claude/skills/node-setup
node-setup
VerifiedAgentic node setup for Cogni forks. Orchestrates the full lifecycle: DAO formation, payment activation, repo identity, infrastructure provisioning, and deploy verification. Delegates to guide docs for step-by-step details.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
SKILL.md
View on GitHub---
name: node-setup
description: "Agentic node setup for Cogni forks. Orchestrates the full lifecycle: DAO formation, payment activation, repo identity, infrastructure provisioning, and deploy verification. Delegates to guide docs for step-by-step details."
---
# Node Setup — Agentic Fork Onboarding
You are an infrastructure setup agent. Your job: take a fresh Cogni fork from clone to **successful preview and production deployments**. Prompt the user only for credentials that require their browser.
## References (read these — they own the details)
- [Node Formation Guide](https://cognidao.org/knowledge/run-node-formation-wizard) — DAO deployment via wizard
- [Payment Activation Guide](https://node-template.cognidao.org/knowledge/set-up-operator-wallet) — Privy wallet + Split contract
- [SETUP_DESIGN.md](https://github.com/cogni-dao/cogni/blob/2321821e61dd12aa0cf75d235bd668ff65739109/scripts/setup/SETUP_DESIGN.md) — canonical secret list, personas, full setup flow
- [https://cognidao.org/knowledge/operator-pipeline-contract Axiom 23](https://cognidao.org/knowledge/operator-pipeline-contract) — `AKASH_IS_NODE_APP_TARGET` (gated north star): new node apps target Akash via the operator compute API; Cherry k3s = state substrate
> ⚠️ Parts of this skill predate the k3s + Akash split (it references retired paths); verify against [cicd-e2e-required-sequence](https://cognidao.org/knowledge/cicd-e2e-required-sequence) before trusting a step.
## Pre-flight
Verify: `gh auth status`, `tofu --version`, `pnpm --version`. Detect repo name from `git remote get-url origin`.
## Node Lifecycle State Machine
```
clone → formation → local env → activation → infra → deploy
(pending) (dev:infra) (active)
```
Check `payments.status` in `.cogni/repo-spec.yaml` to determine current state.
### Phase 0: Formation (`payments.status` missing or no repo-spec)
**Goal:** DAO deployed on-chain, repo-spec generated.
1. Direct user to https://cognidao.org/setup/dao
2. User copies generated YAML into `.cogni/repo-spec.yaml`
3. Follow [Node Formation Guide](https://cognidao.org/knowledge/run-node-formation-wizard) for details
4. **Gate:** `.cogni/repo-spec.yaml` has valid `governance.chain_id` and `payments.status: pending_activation`
### Phase 1: Repo Identity
**Goal:** All template references point to this fork.
Derive `REPO_SLUG` (e.g., `my-cogni-node`) and `REPO_SNAKE` (e.g., `my_cogni_node`) from the repo name. Update:
- `package.json` → `name`
- `.cogni/repo-spec.yaml` → `intent.name`, `activity_sources.github.source_refs`
- `sonar-project.properties` → `sonar.projectKey`, `sonar.projectName`
- `.github/workflows/ci.yaml` → DB names (`REPO_SNAKE_test`)
- `.env.local.example`, `.env.test.example` → DB names
**Gate:** required CI (`unit`, `component`, `static`, `manifest`) is green on the PR.
### Phase 2: Local Environment
**Goal:** `.env.local` configured, dev stack running, database provisioned.
1. Copy `.env.local.example` → `.env.local`, update DB names and `COGNI_REPO_URL`
2. Prompt user for credentials they must create (see [SETUP_DESIGN.md](https://github.com/cogni-dao/cogni/blob/2321821e61dd12aa0cf75d235bd668ff65739109/scripts/setup/SETUP_DESIGN.md) for full list):
| Secret | Where to create |
| -------------------- | --------------------------------------------------------------------------------------- |
| `CHERRY_AUTH_TOKEN` | https://portal.cherryservers.com/settings/api-keys |
| `OPENROUTER_API_KEY` | https://openrouter.ai/settings/keys |
| `EVM_RPC_URL` | https://dashboard.alchemy.com/apps (Base Mainnet) |
| `GHCR_DEPLOY_TOKEN` | https://github.com/settings/tokens/new — **Classic PAT**, `read:packages` scope |
| `GIT_READ_TOKEN` | https://github.com/settings/personal-access-tokens/new — Fine-grained, `Contents: Read` |
3. Auto-generate: `LITELLM_MASTER_KEY`, `AUTH_SECRET` via `openssl rand`
4. Start dev infrastructure: `pnpm dev:infra`
5. Provision database + run migrations: `pnpm dev:setup`
6. Start dev server: `pnpm dev`
**Gate:** required CI (`unit`, `component`, `static`, `manifest`) is green on the PR. App boots at http://localhost:3000 without DB errors.
### Phase 3: Payment Activation (`payments.status: pending_activation`)
**Goal:** Split contract deployed, payments active.
1. User adds `operator_wallet.address` to repo-spec (provision via Privy if needed — see [Payment Activation Guide](https://node-template.cognidao.org/knowledge/set-up-operator-wallet))
2. Restart dev server to pick up repo-spec changes
3. User navigates to http://localhost:3000/setup/dao/payments and deploys Split contract via browser wallet
4. User pastes the output `payments_in` + `payments.status: active` into repo-spec
**Gate:** `payments.status: active` in repo-spec, `payments_in.credits_topup.receiving_address` populated.
### Phase 4: Infrastructure (preview first, then production)
**Goal:** VMs provisioned, SSH keys generated and stored.
Follow [INFRASTRUCTURE_SETUP.md](https://github.com/cogni-dao/cogni/blob/2321821e61dd12aa0cf75d235bd668ff65739109/docs/runbooks/INFRASTRUCTURE_SETUP.md) for detailed steps. Key points:
1. Generate SSH keypairs, commit public keys
2. Discover Cherry project ID via API (never hardcode)
3. Create tfvars (plan: `B1-4-4gb-80s-shared` minimum)
4. `tofu init && tofu apply`
5. Wait for cloud-init (~3 min), verify Docker is running
**Gate:** SSH into VM succeeds, `docker version` works.
### Phase 5: GitHub Secrets
**Goal:** All secrets set for CI/CD deployment.
Follow the secret list in [SETUP_DESIGN.md](https://github.com/cogni-dao/cogni/blob/2321821e61dd12aa0cf75d235bd668ff65739109/scripts/setup/SETUP_DESIGN.md). Three categories:
1. **Auto-generated per env** — DB creds, service tokens, Temporal creds (use `openssl rand`)
2. **From .env.local** — shared credentials (OpenRouter, EVM RPC, PostHog, etc.)
3. **Repo-level** — CHERRY_AUTH_TOKEN, GHCR_DEPLOY_TOKEN, GIT_READ_TOKEN
Set `DOMAIN` as both variable and secret per environment. Ask user for domain names.
**Gate:** `gh secret list --env preview` shows all required secrets.
### Phase 6: DNS
**Goal:** Domain records point to VMs.
Ask user to create A records. Verify with `dig +short <domain>`.
### Phase 7: Deploy & Verify
**Goal:** Green CI run, app responding.
1. Merge to `main` to trigger canary promotion workflow
2. Monitor: `gh run view <id> --json status,conclusion,jobs`
3. On failure: check logs, fix, rerun
4. **Checkpoint:** Preview green → repeat Phases 4-7 for production
**Gate:** `curl -I https://<domain>/readyz` returns 200.
## Done
- [ ] Preview deployment green
- [ ] Production deployment green
- [ ] DNS resolves for both environments
- [ ] `/readyz` returns 200 on both domains
## Anti-patterns
1. **NEVER `source .env.local`** — use `grep` extraction for individual vars
2. **NEVER use fine-grained PATs for GHCR** — only Classic PATs work
3. **NEVER use 2GB VMs** — full stack requires 4GB minimum
4. **NEVER hardcode `cogni-template` names** — derive from repo name
5. **NEVER trust `/v1/regions` for auth verification** — it's public; use `/v1/teams`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |