PERN Template Guide

This file is specific to the pern template.

hackctl Context

• This template is scaffolded by hackctl create --template pern.
• hackctl start reads service definitions from hackctl.config.json.
• hackctl share uses share.defaultService and share.defaultPort from hackctl.config.json.
• hackctl deploy reads the template deploy block and currently expects runtime: pm2 with mode: dev.
• hackctl status and hackctl destroy read saved deploy metadata from .hackctl/deploy.json.

hackctl.config.json Contract

• Keep the schema URL as https://hackctl.dev/schemas/hackctl.config.v1.json.
• Keep both services aligned with real directories and commands:
  • frontend -> cwd: frontend, run: npm run dev, port: 3000
  • backend -> cwd: backend, run: npm run dev, port: 5000, envFile: backend/.env
• Keep the deploy block aligned with the current remote contract:
  • runtime: pm2
  • mode: dev
• If service names, ports, or folder layout change, update hackctl.config.json and README.md together.
• Frontend API calls should remain on relative /api/* paths, with proxy target controlled by env.

Runtime State

• hackctl start and hackctl share write local runtime data to .hackctl/state.json.
• hackctl deploy writes remote deploy metadata to .hackctl/deploy.json.
• .hackctl/ must stay gitignored.
• Never commit .hackctl/state.json, .hackctl/deploy.json, or other local runtime artifacts.

AI Guidance Files

• AGENTS.md is the canonical guidance file.
• CLAUDE.md and GEMINI.md should remain lightweight pointers to this file.
• Keep guidance grounded in shipped behavior for this template.