If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ponzu-cms/ponzu shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 15 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ponzu-cms/ponzu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ponzu-cms/ponzu.

What it runs against: a local clone of ponzu-cms/ponzu — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ponzu-cms/ponzu | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 201 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ponzu-cms/ponzu. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ponzu-cms/ponzu.git
#   cd ponzu
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ponzu-cms/ponzu and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ponzu-cms/ponzu(\\.git)?\\b" \\
  && ok "origin remote is ponzu-cms/ponzu" \\
  || miss "origin remote is not ponzu-cms/ponzu (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 201 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~171d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ponzu-cms/ponzu"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Ponzu is a headless CMS and HTTP server framework written in Go that automatically generates JSON APIs from content type definitions. It bundles automatic HTTPS via Let's Encrypt, HTTP/2 Server Push, and a web-based admin UI for managing structured content — letting you run ponzu gen content song title:"string" artist:"string" to instantly scaffold a content type with an editor and REST endpoint. Monorepo structure: cmd/ponzu/ contains the CLI tool with subcommands (new, gen, add, build, upgrade) and Go template generators (cmd/ponzu/templates/gen-*.tmpl) for scaffolding content types. addons/github.com/bosssauce/ provides plugin architecture. The vendored BoltDB in cmd/ponzu/vendor/ handles data persistence. CircleCI config in .circleci/ manages CI/CD.

Backend developers and startup teams building content-driven applications (blogs, media platforms, mobile app backends) who need a fast JSON API server without the overhead of WordPress/Rails but want a visual CMS for non-technical editors. Go developers comfortable with server-side code generation.

ABANDONED — The README displays an orange 'Abandoned' badge and actively directs users to Caddy Server instead. The project has no recent commits visible in the file list, and maintainers are explicitly being sought at support@zerossl.com. Not suitable for new production projects.

Critical: The project is officially abandoned with no active maintenance. BoltDB (embedded in cmd/ponzu/vendor/) is a legacy embedded database with known limitations. No obvious test coverage visible in the top 60 files. The reliance on Let's Encrypt and TLS requires external service availability. Migration path is unclear if you're already using it.

Nothing — the project is abandoned. The last meaningful activity appears to have been the deprecation notice and redirect to Caddy Server. No active PRs, issues, or development are visible.

⚠️ Not recommended for new projects. For historical exploration only:

git clone https://github.com/ponzu-cms/ponzu.git
cd ponzu/cmd/ponzu
go build -o ponzu .
./ponzu new myproject
cd myproject
./ponzu build
./ponzu run

However, the project will not receive security updates or bug fixes.

Daily commands: From cmd/ponzu/: go build -o ponzu → ./ponzu new <project-name> → cd <project-name> → ./ponzu build → ./ponzu run (default port 6843 with auto-HTTPS). CircleCI test script in .circleci/test-run.sh shows full setup.

• cmd/ponzu/main.go: Entry point for the CLI tool; dispatches to subcommands (new, gen, add, build, run).
• cmd/ponzu/generate.go: Implements the gen content command that parses field definitions and invokes template generators.
• cmd/ponzu/templates/gen-content.tmpl: Master template that scaffolds the Go struct and admin UI for a new content type.
• cmd/ponzu/new.go: Bootstraps a new Ponzu project with directory structure, sample content types, and config.
• cmd/ponzu/build.go: Compiles the generated code and content types into a standalone binary ready for deployment.
• cmd/ponzu/ponzu.json: Project configuration file (generated per-project) specifying content types, port, TLS cert paths, and custom settings.
• .circleci/config.yml: CI/CD pipeline definition; shows how the project is tested and released (now defunct due to abandonment).

Content Types: Edit or create files in content/ directory (auto-generated). Admin UI: Modify templates in cmd/ponzu/templates/gen-*.tmpl to change scaffolded editor fields. Addons: Place Go plugins in addons/github.com/<author>/ and register in your project. CLI Commands: Edit cmd/ponzu/*.go (add.go, generate.go, etc.) to extend CLI. Server Logic: Hooks are added in generated content files.

CRITICAL: Project is abandoned — expect zero support, no security patches, and potential incompatibility with modern Go versions and Let's Encrypt API changes. Auto-HTTPS requires outbound ACME access to Let's Encrypt (port 443, DNS validation). BoltDB is file-locked per-process, so concurrent write access from multiple binaries will fail. CLI tool must be re-run after content struct changes (ponzu build) to regenerate the JSON API. No database migrations — schema changes require manual BoltDB manipulation. Templating quirks: gen-*.tmpl files use custom delimiters; modifying them without understanding the generator will break scaffolding.

• Headless CMS — Ponzu's core concept — separating content management UI from API delivery allows decoupled frontend consumption (web, mobile, IoT) without template coupling.
• Code Generation (via Templates) — Ponzu's differentiator: CLI commands invoke Go text/template files to auto-generate Go structs, editors, and API handlers from declarative field definitions; avoids boilerplate.
• Let's Encrypt ACME Protocol — Ponzu bundles automatic TLS certificate provisioning via Let's Encrypt; essential to understand ACME challenges, renewal cycles, and outbound network requirements.
• HTTP/2 Server Push — Ponzu advertises HTTP/2 Server Push for proactive resource delivery; understand when push helps (small static assets) vs. hurts (unnecessary bandwidth).
• BoltDB (Embedded Key-Value Store) — Ponzu uses BoltDB for data persistence; it's file-locked, single-process, ACID-compliant, and suitable for small-to-medium deployments but not horizontally scalable.
• Content Scaffolding / Rapid CRUD Generation — Ponzu's hook: ponzu gen content introspects field type strings and generates full editor + API layers; understand how metadata-driven code generation reduces repetition.
• Plugin Architecture via Addons — Ponzu extends via Go packages in addons/; plugins can hook into content lifecycle and API routes, requiring understanding of Go package imports and runtime composition.

• caddyserver/caddy — The official successor — Ponzu's README actively directs users here for HTTP/2, auto-HTTPS, and TLS; Caddy is Ponzu's replacement for the server infrastructure layer.
• strapi/strapi — Modern alternative headless CMS in Node.js with similar content scaffolding, auto-API generation, and plugin system; the spiritual successor to Ponzu's problem space.
• getkirby/kirby — Lightweight flat-file/database-agnostic CMS offering content type definition and API generation without Ponzu's infrastructure focus.
• boltdb/bolt — The embedded database used by Ponzu (vendored in cmd/ponzu/vendor/github.com/boltdb/bolt) for key-value storage; worth understanding for data layer.
• go-chi/chi — Modern Go HTTP router that Ponzu-like projects use today for cleaner HTTP handler composition; shows post-Ponzu patterns for Go HTTP servers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for cmd/ponzu CLI generation templates

The repo contains 11 template files (gen-*.tmpl) for code generation but only has cli_test.go and new_test.go with minimal coverage. The generate.go, add.go, and build.go commands lack tests for template rendering and file output. This is critical for a code generation tool to prevent breaking changes to generated content.

• [ ] Review cmd/ponzu/generate.go and cmd/ponzu/add.go to understand template rendering logic
• [ ] Create cmd/ponzu/generate_test.go with tests covering each template type (checkbox, input, textarea, richtext, select, file, reference, repeater variants)
• [ ] Add tests for template variable substitution and Go code syntax validation
• [ ] Verify generated files parse correctly with go/parser package
• [ ] Add test fixtures showing expected output for each template type

Refactor cmd/ponzu vendor dependencies to use Go modules

The repository still uses vendored dependencies (cmd/ponzu/vendor/) for BoltDB and likely others, which is an outdated Go dependency management pattern. Modern Go (1.11+) uses go.mod/go.sum. This blocks contributors from understanding true dependencies, complicates security updates, and prevents using go get workflows.

• [ ] Create a go.mod file in the cmd/ponzu directory listing all vendored dependencies with versions
• [ ] Run 'go mod tidy' to validate and generate go.sum
• [ ] Remove cmd/ponzu/vendor directory entirely
• [ ] Update .gitignore to ignore vendor/ if needed for local builds
• [ ] Verify all cmd/ponzu commands still build successfully
• [ ] Update CONTRIBUTING.md with module-based setup instructions

Add CircleCI workflow for testing generated CMS projects

The .circleci/test-run.sh and test-setup.sh exist but the config.yml likely only tests the ponzu CLI itself. There's no verification that 'ponzu new' generates a working project or that the generated admin UI actually starts. This is critical for a code generation tool to catch regressions in generated content structure.

• [ ] Review .circleci/config.yml to identify existing test jobs
• [ ] Create a new CircleCI job that runs 'ponzu new testproject' to generate a fresh CMS
• [ ] Add steps to build the generated project with 'ponzu build' in the testproject
• [ ] Verify the generated project directory structure matches expectations with test assertions
• [ ] Add checks for critical generated files (content types, schema, handlers)
• [ ] Update .circleci/test-run.sh to include these validation steps

• Write integration tests for cmd/ponzu/cli_test.go and cmd/ponzu/new_test.go covering the gen, build, and run workflows — only 2 test files exist for a 350K LOC codebase.
• Document the addon system with a complete worked example in addons/README.md beyond the reference plugin — show how to hook into content lifecycle events (create, update, delete).
• Add schema validation to cmd/ponzu/ponzu.json (currently unvalidated) to catch malformed project configs early and provide friendly error messages instead of cryptic failures during build.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.