Skip to content

skills: build/run from source, cloud brain, projectors + BEYOND + Palace - #155

Merged
pyramation merged 2 commits into
mainfrom
devin/1794564123-agent-skills
Nov 13, 2026
Merged

pyramation merged 2 commits into
mainfrom
devin/1794564123-agent-skills

Conversation

@pyramation

Copy link
Copy Markdown
Contributor

Summary

Adds three agent skills in .agents/skills/ and lists them in the README. With these, a new agent can build, run and deploy everything without reconstructing it from chat history. No code changes.

  • wavegrid-dev-build: install, pnpm build, lint, test, and the package map. Running the CLI from packages/cli/dist/bin.js (npm can lag behind main). A local show for UI work, and capturing UI screenshots over CDP. Gotchas:
    • Run the full test suite with a clean HOME, or a local ~/.wavegrid layout breaks config.test.ts.
    • The server and the desktop serve the built UI.
    • Port 3000 may already be taken.
    • A layout change needs a stop and start.
  • wavegrid-cloud-brain: the hipzap.com deployment (droplet, ufw, systemd server --project, and nginx with WebSocket upgrade and 1-day timeouts). Deploying a new main over SSH with git archive. Users and roles (the first user is admin and the CLI has no role flag; POST /api/admin/users/<name>/role). Secrets (jwtSecret, receiverKey, .wgproj). The rule that every receiver runs the brain's exact commit. No secrets are included.
  • wavegrid-projectors-beyond: fixture kind, the interleaved zipper layout, the BEYOND livecontrol OSC paths, the routing file (routing only, never alongside projects osc beyond), finding the zone base with signals probe/--keep-zones, BEYOND.ini and the RGBA panel, the Windows receiver from source, how the Palace pattern works and how to extend it, the dormant projector/projector_cue API, and Class IV safety.

Link to Devin session: https://app.devin.ai/sessions/e6939c79261649988b8277ba34725160
Open in Devin Desktop: https://app.devin.ai/desktop/session/e6939c79261649988b8277ba34725160?variant=devin
Requested by: @pyramation

@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Review complete. 🟡 3 medium

💬 Inline comments (3)

  • 🟡 Receiver-provisioning export command omits --include-secrets — SKILL.md:83
  • 🟡 Deploy procedure breaks the same-commit guarantee it mandates — SKILL.md:62
  • 🟡 systemd unit lacks [Install], brain stays down after reboot — SKILL.md:29
🧹 Nitpicks (1) — 🟢 1 low
  • 🟢 Frame dual-configuration double-send as a safety hazard (SKILL.md:33) — The dual-configuration hazard — routing plus projects osc beyond … causing every zone to be sent twice — is documented only as a functional bug in the Routing section (.agents/skills/wavegrid-projectors-beyond/SKILL.md:33), with no cross-reference from the Class IV Safety section.

This PR introduces no code changes; it adds three new skill documents under .agents/skills/ and wires them plus the dev-build guide into the README skill table. The runbooks document the cloud-brain deployment path, a BEYOND-projector rig setup, and the local build workflow with a package map and known gotchas. Verified issues concentrate in the cloud-brain runbook: a provisioning export command that omits --include-secrets, a deploy sequence that violates its own same-commit guarantee, and a systemd unit missing an [Install] section so the brain does not start on reboot. The projector guide also understates the dual-configuration double-send hazard.

Files Change
.agents/skills/wavegrid-cloud-brain/SKILL.md New runbook: systemd/nginx/certbot cloud deployment, SSH git-archive deploy, users, receiver keys, live-site safety
.agents/skills/wavegrid-projectors-beyond/SKILL.md New runbook: BEYOND projector rig setup, interleaved routing, OSC live control, Class IV safety
.agents/skills/wavegrid-dev-build/SKILL.md New guide: monorepo build order, package map, test/lint commands, common gotchas
README.md Adds table rows linking the three new skills into the skills index

Reviewed commit: af52dee

@pyramation
pyramation merged commit 3e7acdb into main Nov 13, 2026
5 checks passed

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adds four documentation guides (three agent skill runbooks plus README rows) covering dev build, cloud-brain deployment, distributed shows, and BEYOND projector integration.

Key findings

  • 🟡 Receiver-provisioning export command omits --include-secrets — SKILL.md:83
  • 🟡 Deploy procedure breaks the same-commit guarantee it mandates — SKILL.md:62
  • 🟡 systemd unit lacks [Install], brain stays down after reboot — SKILL.md:29


The first user in a project is `admin`; later ones are `operator` (they can drive the show but not manage users or keys). The CLI has no role flag. An admin changes a role in the desktop app's user management, or with `POST /api/admin/users/<name>/role {"role":"admin"}` using an admin login token. Re-adding an existing user changes the password and keeps the role.

Changing a password does not log out existing sessions (the JWTs stay valid). The project secrets are `jwtSecret` (signs UI logins) and `receiverKey` (what a receiver presents). Give a receiver the project with `projects export --out <p>.wgproj`, then `projects import <p>.wgproj --activate` and `projects config set receiver.server wss://<domain>` on the receiver. The bundle contains both secrets, so treat it like a password. Only a new `receiverKey` has to be copied back out to receivers.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

Receiver-provisioning export command omits --include-secrets

The runbook says projects export --out <p>.wgproj gives a receiver the project and that "The bundle contains both secrets" (.agents/skills/wavegrid-cloud-brain/SKILL.md:83), but runProjectsExport includes secrets only when --include-secrets is passed (packages/cli/src/commands/project-io.ts:19). Following the documented command, the receiver's import generates fresh secrets and prints that it will not connect to the original brain. Every receiver provisioned this way can never join the hipzap.com brain.

📋 Prompt for AI Agents

In .agents/skills/wavegrid-cloud-brain/SKILL.md line 83, the receiver-provisioning command projects export --out <p>.wgproj is missing --include-secrets, yet the same sentence claims the bundle contains jwtSecret and receiverKey. Per packages/cli/src/commands/project-io.ts:19, secrets are exported only with that flag. Fix the command to projects export --include-secrets --out <p>.wgproj so the receiver import actually carries the shared keys.

Comment on lines +62 to +63
git checkout main && git pull
git archive HEAD | ssh root@<ip> 'tar -x -C /opt/wavegrid && chown -R wavegrid:wavegrid /opt/wavegrid \

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

Deploy procedure breaks the same-commit guarantee it mandates

The deploy runs git checkout main && git pull and ships git archive HEAD to the droplet without ever pushing (.agents/skills/wavegrid-cloud-brain/SKILL.md:62-63), while receivers are told to git pull from GitHub (line 68). If the operator's local main holds any unpushed commit, the brain runs code receivers cannot obtain, producing exactly the version-skew failure the runbook warns about. Add the push (or an origin/main check) before archiving.

📋 Prompt for AI Agents

In .agents/skills/wavegrid-cloud-brain/SKILL.md lines 61-68, the deploy archives local HEAD to the droplet but never pushes to GitHub, while receivers are told to git pull. Insert an explicit git push origin main (or verify HEAD equals origin/main) before the git archive command, and note that receivers must pull that same commit.

Comment on lines +29 to +37
```ini
[Service]
User=wavegrid
WorkingDirectory=/opt/wavegrid
ExecStart=/usr/bin/node /opt/wavegrid/packages/cli/dist/bin.js server --project <project>
Restart=always
Environment=NODE_ENV=production
StandardInput=null
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

systemd unit lacks [Install], brain stays down after reboot

The documented wavegrid.service contains only a [Service] section (.agents/skills/wavegrid-cloud-brain/SKILL.md:29-37), with no [Unit] header and no [Install] WantedBy=multi-user.target. systemctl enable wavegrid fails on such a unit, so after a droplet reboot the brain — and every venue receiver dialling into it — stays down until someone SSHes in. The runbook's setup steps also never enable the unit.

📋 Prompt for AI Agents

In .agents/skills/wavegrid-cloud-brain/SKILL.md lines 29-37, extend the wavegrid.service snippet with a [Unit] section (Description, After=network-online.target) and an [Install] section with WantedBy=multi-user.target, and add systemctl enable wavegrid to the setup steps so the brain restarts automatically after a droplet reboot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant