Theme Updates and Core Boundaries

AstroWEBTheme should be easy to update without damaging a client project. That requires a clear boundary between reusable theme internals and project-owned files.

Reusable Core

The core/ directory contains reusable theme internals:

• layout helpers
• content resolvers
• schema builders
• generated asset tools
• media sync tools
• auth and dashboard primitives
• Cloudflare helpers

Agents should edit core/ only when the change improves the reusable theme itself.

Project-Owned Areas

Project-specific work usually belongs in:

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

These paths should be treated as user-owned in client projects.

Lock Flags

Collection and page config can use lock flags to mark routes or pages as user-owned. Scaffold and update commands should respect those flags.

The principle is simple:

locked files are not overwritten automatically

Agent Update Rules

When an agent updates the theme:

1. Read AGENTS.md.
2. Read astrowebtheme.json.
3. Check the git status.
4. Identify user-owned changes.
5. Keep updates focused.
6. Show diffs for risky files.
7. Do not reset unrelated changes.
8. Run a build when behavior changes.

Generated Files

Some files are generated during build or prebuild:

• CSS bundles in public/styles/
• JS bundles in public/scripts/
• manifests in src/data/manifest/
• search indexes in public/search/
• Cloudflare config in wrangler.jsonc

If a source file changes, run the matching generator rather than editing generated output by hand.

Future Direction

The long-term goal is an agent-assisted install/update flow where the agent can:

• detect an AstroWEBTheme project
• read the manifest
• apply safe scaffolds
• preserve user files
• run dry checks
• explain required manual steps

This is what makes the theme different from a one-time template.