Portable_Web_toolkit AGENTS.md

Portable Web Toolkit — Agent Instructions

Blind agents: read START_HERE.md first — zero research required.

Repo-local rules for AI agents using the Portable Astro + Cloudflare Web Toolkit (Web_Toolkit/).

Read first (in order)

1. The active client repository's applicable instructions when operating on a client site
2. START_HERE.md for toolkit orientation
3. The narrow installed skill in skills/
4. Web_Toolkit/OPERATIONS.md only when detailed operations are relevant
5. Current source, manifests, profiles, tests, and runtime evidence

Do not load docs/templates/AGENT.template.md for toolkit work — that template is for other projects.

Toolkit root

All operator modules live under:

Web_Toolkit/

Site-specific behavior comes from site-profiles/*.json (or a private profile path passed with --site-profile). Live secrets belong in the target project root .env, not in the toolkit tree.

Authority and precedence

Follow the host's actual system, administrator, user, repository, and nested instruction precedence.

When operating on a client site:

1. client-repository instructions and approved runbooks govern that site
2. current source, manifests, tests, and runtime evidence establish state
3. Portable Web Toolkit skills supply subordinate domain procedures
4. toolkit documentation supplies conditional reference material

This file governs work on the toolkit repository itself. It does not outrank a client repository merely because Web_Toolkit is linked into that project.

Configuration has scoped authority, not instruction precedence:

• a site profile owns its declared deployment configuration
• a Brand Guide owns approved visual identity and voice
• .env supplies local values and bindings
• manifests and lockfiles own package state

None of these override safety policy or explicit repository constraints.

Core rules

• Spec-driven: read the site profile before deploy, DNS, or branding changes.
• Dry-run first: infrastructure and Cloudflare mutations → audit → dry-run → --apply.
• Runtime artifacts: keep generated output in Web_Toolkit/.runtime/, not in publishable source.
• Discovery layer: use the established toolkit generators and discovery-doctor when the client repository adopts that contract. Do not create a parallel generator.
• Styles: external CSS in src/styles/ with tokens; run stylesheet-check scan --root <project> when changing UI CSS.
• Accessibility: toolkit sites use bundled Web_Toolkit/wcag_auditor only — never resolve AI/wcag-auditor or other trees outside the linked toolkit. Evidence gate — not a conformance certificate.
• Assets: no stock/placeholder favicons or heroes; Astro Image/Picture (astro:assets, imageService: 'compile' on Workers) for content photos — prefer OptimizedPicture with AVIF+WebP. image-pipeline only for leftover public/ rasters. SVG masters for icons/logos.
• Workers-over-external: prefer Cloudflare Workers/bindings (KV, D1, R2, Vectorize) before adding SaaS.
• Version truth: verify Astro/Wrangler/Node from repo + registry — never trust stale model memory.