Installing AstroWEBTheme With an AI Agent

Installing AstroWEBTheme With an AI Agent

A practical guide for using Codex or another AI coding agent to install, configure, and verify AstroWEBTheme safely.

By · Updated

AstroWEBTheme is designed to become easy for AI coding agents to install, inspect, configure, and update. The goal is not just a theme that looks good, but a theme with a clear project contract.

Before asking an agent to work on a project, point it to:

  • AGENTS.md
  • astrowebtheme.json
  • package.json
  • src/site/config/pages.mjs
  • src/site/config/content.mjs
  • src/site/config/security.mjs

These files explain the theme role, safe edit zones, Cloudflare bindings, content sources, collection flags, and build commands.

Use a direct prompt like this:

Install and configure AstroWEBTheme for this client site. Read AGENTS.md and astrowebtheme.json first. Preserve existing content and styles. Use src/site/ for client-specific changes. Do not overwrite user-owned files without showing a diff. Run the build after changes.

For an existing site, add the extra instruction:

Treat the current worktree as user-owned. Do not delete existing pages, content, styles, or config unless I explicitly approve it.

Safe Installation Flow

  1. Read the project contract.
  2. Inspect the worktree and existing routes.
  3. Identify whether this is a new site, demo site, or theme package.
  4. Configure site identity in src/site/config/info.mjs.
  5. Configure collections in src/site/config/pages.mjs.
  6. Configure live/static content mode in src/site/config/content.mjs.
  7. Configure security headers in src/site/config/security.mjs.
  8. Add or update content under src/site/content/.
  9. Run CSS and manifest generation when styles or assets change.
  10. Run a build and report any unrelated existing errors separately.

Safe Edit Zones

Most client-specific work should happen in:

  • src/site/content/
  • src/site/config/
  • src/site/styles/
  • src/components/
  • src/layouts/
  • docs/
  • migrations/

The agent should be more careful with:

  • core/
  • core/scripts/
  • src/data/manifest/
  • public/
  • wrangler.jsonc
  • .dev.vars

What the Agent Should Verify

After installation or configuration, the agent should verify:

  • Homepage renders.
  • /docs/ renders.
  • /llms.txt returns useful text.
  • /rss.xml returns current content.
  • /sitemap.xml exists.
  • Content Security Policy is header-based in production mode.
  • Consent banner scripts load through the manifest.
  • D1/R2 pages fail gracefully when local bindings are unavailable.

Why This Matters

Agent-installed websites need predictable structure. AstroWEBTheme gives agents a map of where content lives, where reusable theme internals live, how to publish live content, and how to avoid damaging user-owned files.

That makes the theme useful for agencies, solo builders, product teams, service businesses, and documentation sites that expect AI assistants to help maintain the website over time.