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. The doctor requires the core llms/humans/security/content discovery artifacts by default; explicitly relaxed or runtime-only resources are INFO when absent, while present-but-invalid resources fail. 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 Web_Toolkit/wcag_auditor (WCAGate wrapper) only — never resolve AI/wcag-auditor. Engine is github:imyourboyroy/WCAGate in Web_Toolkit/node_modules. 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.
• Automatic freshness: toolkit entrypoints perform a throttled update check; only a clean public main checkout may fast-forward, while WCAGate follows its unpinned public main dependency. Dirty or unmanaged state is reported and preserved.

Canonical sequence (summary)

For material work without current readiness evidence, start with:

node ./Web_Toolkit/site_readiness/bin/site-readiness.mjs run --project-root <site> --site-profile <profile>

See Web_Toolkit/OPERATIONS.md for the full numbered list. Short form:

1. Toolkit freshness preflight (automatic; inspect .runtime/toolkit-auto-update.json on warning/error)
2. site-readiness run (or project-init apply-safe on fresh folders)
3. init_site_profile or load existing profile
4. Build: npm run check → npm run build
5. discovery-doctor on ./dist before deploy (with --site-profile for the active discovery contract); again on live URL after prod
6. Staging deploy + smoke before production
7. cf-agent audits — dry-run hardening first
8. Before sharing toolkit: toolkit-purge --apply, privacy-check, toolkit-verify

Key CLI entry points

Pass --site-profile <path> whenever the target site is not the default example profile.

Verification before completion

• Site profile loaded and respected
• Dry-run outputs reviewed before any --apply
• discovery-doctor passes on dist/ (and live URL if deployed)
• No secrets in committed files or toolkit export
• Client project MEMORY.md updated when versions/deploy change (when applicable)

Skill distribution

See docs/agent-skills/README.md

Inspect and install the selected Portable Web Toolkit skills from the repository
manifest. Check existing client skill directories first, preserve conflicts,
and change only explicitly selected clients and skills.

Core: portable-web-toolkit-router (global default), site-onboarding, portable-web-toolkit, site-readiness, site-starter, site-maintenance, wcag-auditor, pagespeed-diagnostics, discovery-doctor, toolkit-update

Optional: brand-doctor, image-pipeline, instagram-clone, vectorize-pipeline

Optional helper scripts default to status. Agent-driven installation remains the primary path.