@topy-ai/maggie 0.1.0

package/bundled-skills/maggie-clone/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: maggie-clone
+description: Reverse-engineer one or more authorized websites and create matching pages inside an existing Maggie blog project. Use with /maggie-clone <target-url1> [<target-url2> ...] when a user wants to replicate a page's structure, content, assets, responsive behavior, and interactions.
+argument-hint: "<target-url1> [<target-url2> ...]"
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Clone
+
+Create one or more website-inspired pages inside an existing Maggie blog
+project. This workflow is for authorized sites and pages. It preserves the
+host project's bootstrap foundation, public blog routes, content contracts,
+SEO safeguards, and existing user work while adding namespaced page output.
+
+Invoke it as:
+
+```text
+/maggie-clone <target-url1> [<target-url2> ...]
+```
+
+The URL path becomes the default destination path. Multiple URLs from one
+origin remain separate routes; query strings and fragments are inspected for
+state but do not silently create duplicate routes.
+
+## Boundaries
+
+- Run `maggie-blog-bootstrap` first. Require a completed
+  `.maggie/bootstrap-state.json`; if it is absent, stop and ask the user to
+  bootstrap the project.
+- Analyze the host project before editing. Never replace its framework, UI
+  system, icon set, fonts, database, blog routes, metadata, sitemap, or
+  analytics merely to match the target.
+- Clone presentation and behavior, not credentials, private data, tracking
+  secrets, checkout flows, authentication, or proprietary backend logic.
+- Use real public assets only when the user is authorized to reproduce them.
+  Preserve attribution or licensing requirements and report assets that could
+  not be safely reused.
+- The clone is an additive page operation. Do not overwrite an existing route,
+  component namespace, asset namespace, or research artifact without explicit
+  approval.
+- Keep AI CMO writes, publishing, and external deployment separate from local
+  page construction. A clone does not automatically create, publish, or queue
+  content in Maggie.
+
+## Required browser capability
+
+Browser automation is required. Use the available Chrome/browser/Playwright
+MCP or equivalent browser tool to inspect the target, take screenshots, resize
+the viewport, scroll, click, hover, and evaluate DOM/computed styles. Read
+[`references/browser-inspection.md`](../../references/browser-inspection.md)
+for the inspection contract. If no browser tool is available, stop before
+editing and report the missing capability.
+
+## Phase 0: Preflight and plan
+
+1. Parse and normalize all target URLs. Reject invalid, inaccessible, or
+   ambiguous URLs before writing files.
+2. Run:
+
+   ```bash
+   python3 tools/clis/maggie.py status <project-root>
+   python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
+   python3 tools/clis/maggie_clone.py plan <url1> [<url2> ...] --project <project-root>
+   ```
+
+   The clone planner emits collision-resistant site/page keys and destination
+   namespaces. Treat its output as the route and artifact plan.
+3. Inventory existing `src/app`, `src/pages`, public routes, blog components,
+   `docs/research`, screenshots, downloaded assets, redirects, sitemap,
+   robots, metadata, and analytics. Record what will remain unchanged.
+4. Run the host project's build or typecheck gate before editing. If the
+   project is already broken, report it and do not attribute the failure to
+   the clone.
+5. For URLs from different origins, ask for separate project roots or explicit
+   approval for a combined route-scoped app. Do not mix global fonts or CSS
+   foundations silently.
+
+Write an output plan before implementation containing, for every URL:
+
+```text
+source URL -> destination route
+site key / page key
+research artifact root
+screenshot root
+component namespace
+asset namespace
+existing files preserved
+shared foundation files that may change
+```
+
+## Phase 1: Reconnaissance
+
+Inspect the target before building it. Capture desktop (1440px), tablet
+(768px), and mobile (390px) views. For each target record:
+
+- page topology from top to bottom and fixed/sticky layers;
+- exact visible text, links, labels, alt text, forms, and public content;
+- fonts, weights, colors, spacing, breakpoints, radii, shadows, gradients,
+  borders, and responsive layout changes from computed styles;
+- every image, video, SVG, favicon, font, background image, and layered asset;
+- interaction models: static, click-driven, hover-driven, scroll-driven,
+  intersection-observer-driven, keyboard, or time-driven;
+- loading, empty, error, open, active, hover, and scrolled states where
+  observable;
+- framework and client behavior clues without copying private implementation
+  details.
+
+Do not click first when a section may be scroll-driven. Scroll slowly, then
+test clicks and hovers. For tabs or pills, capture every state. For headers or
+sticky elements, record before/after computed values and the trigger.
+
+Persist the evidence before building:
+
+```text
+docs/research/<site-key>/<page-key>/
+  OUTPUT_PLAN.md
+  PAGE_TOPOLOGY.md
+  BEHAVIORS.md
+  DESIGN_TOKENS.md
+  COMPONENT_INVENTORY.md
+  LAYOUT_ARCHITECTURE.md
+  TECH_STACK_ANALYSIS.md
+  ASSET_MANIFEST.md
+  components/<component>.spec.md
+docs/design-references/<site-key>/<page-key>/
+  desktop.png, tablet.png, mobile.png, and state screenshots
+```
+
+Every component spec must be written before its builder work starts. Include
+the target file, screenshot, DOM structure, exact computed values, all states,
+verbatim content, assets, interaction model, and desktop/tablet/mobile
+behavior. Never ask a builder to guess values or merely “read the docs”.
+
+## Phase 2: Foundation and assets
+
+After the user approves the plan where it changes shared foundations:
+
+1. Keep the existing Maggie bootstrap contracts and add only route-scoped
+   tokens or components unless a style is genuinely shared.
+2. Reuse the host's existing UI primitives, icon library, font, and data
+   contracts. Extract target SVGs into the site-scoped namespace only when
+   authorized and necessary.
+3. Download public assets into the planned namespaced directory with a unique
+   downloader. Validate status, content type, dimensions, and filename; never
+   overwrite another target's file. Record source URL, local path, license or
+   reuse note, and failures in `ASSET_MANIFEST.md`.
+4. Do not use generated artwork as a substitute for a logo, trademark,
+   product screenshot, certification mark, or other distinctive asset. Report
+   unrecoverable assets instead.
+5. Keep external keys and analytics IDs server-side. The cloned page must not
+   inherit the target's tracking identifiers.
+
+## Phase 3: Build and assemble
+
+Build small components from the approved specs. For complex sections, split
+sub-components before the wrapper. Put output under the planner's site/page
+namespace, for example:
+
+```text
+src/components/sites/<site-key>/<page-key>/
+public/sites/<site-key>/<page-key>/
+src/app/<destination-path>/page.tsx
+```
+
+Use the exact normalized destination route. A first clone may use `/` only in
+an untouched scaffold; otherwise preserve the source pathname or the user-
+approved destination. Preserve all existing routes and use real 404 behavior.
+
+Implement observed behavior, including responsive layout, scroll transitions,
+hover/focus states, tabs, dialogs, carousels, and reduced-motion behavior. Do
+not turn a scroll-driven interaction into a click-only tab or replace a video
+with a guessed HTML mockup.
+
+The cloned page remains a Maggie blog project page:
+
+- use the host's canonical URL and metadata helpers;
+- keep sitemap inclusion explicit and published-only;
+- keep Article/BlogPosting JSON-LD limited to actual posts, not arbitrary
+  marketing pages;
+- preserve robots, analytics opt-out behavior, security headers, and API key
+  boundaries;
+- if the page is a blog landing or post route, map it to the stable Maggie post
+  contract instead of inventing fields.
+
+## Phase 4: Verification
+
+For every target:
+
+1. Run the host typecheck/lint/build commands and `doctor --strict`.
+2. Verify the exact destination URL, neighboring blog routes, 404 behavior,
+   sitemap, robots, canonical metadata, Open Graph, and JSON-LD.
+3. Take same-viewport screenshots of target and local page at 1440px and
+   390px; compare section by section and fix measured discrepancies.
+4. Re-run the interaction sweep: scroll, click, hover, keyboard focus, open
+   menus/dialogs, and responsive resizing.
+5. Run:
+
+   ```bash
+   python3 tools/clis/site_audit.py <local-or-production-url> --json
+   python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
+   ```
+
+Do not claim pixel fidelity when a target asset, authenticated state, blocked
+browser behavior, or dynamic backend could not be inspected. Report remaining
+differences and whether they are known, measured, or unverified.
+
+## Completion report
+
+Report source-to-route mappings, preserved routes, sections/components/specs,
+assets downloaded and failed, files changed, commands run, build/audit status,
+visual QA result, and known limitations. Deployment, API Pull, rewrite, and
+publication require a separate explicit request.

package/bundled-skills/maggie-deployment/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: maggie-deployment
+description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Deployment
+
+Deploy a confirmed Maggie blog to a real hosting target. Cloudflare Workers is
+the default target for dynamic Astro sites; use the Cloudflare reference for
+Worker, D1, R2, KV, secrets, environments, and verification details.
+
+## Required workflow
+
+1. Run `python3 tools/clis/maggie.py analyze <project> --save` and inspect the
+   selected framework, runtime, build/deploy commands, route inventory, data
+   layer, and deployment risks.
+2. Confirm the target, domain, environment (`staging` or `production`), data
+   store, media store, secret names, and rollback owner before any external
+   mutation. Production deploy is never implied by a build request.
+3. Run the host project's typecheck/build/contract/SEO gates. A Cloudflare
+   build must not include Node-only persistence or filesystem writes in Worker
+   request paths.
+4. Provision or bind only the resources declared by the target manifest. Keep
+   D1/KV/R2 IDs and provider secrets in Wrangler/secret-manager configuration,
+   never in source, generated reports, or client bundles.
+5. Deploy staging first, run the deployed route/metadata/sitemap/robots/API
+   smoke checks, then request explicit production approval.
+6. Record deployment URL, commit, environment, bindings, migration version,
+   verification result, and rollback command in the project's handover state.
+
+## Cloudflare default
+
+The Astro starter includes a Cloudflare Worker target in `wrangler.jsonc` and
+uses `@astrojs/cloudflare` when `MAGGIE_DEPLOY_PROVIDER=cloudflare`. The local
+Node target remains useful for SQLite development. Do not claim the Worker is
+production-ready while `better-sqlite3`, `node:fs`, or another Node-only module
+is on a request path; follow [cloudflare.md](references/cloudflare.md) to move
+the database to D1 and media to R2/Cloudflare Images or an explicitly selected
+external adapter.
+
+## Provider boundary
+
+Deployment providers implement the same conceptual operations:
+
+```text
+inspect → plan → provision/bind → migrate → build → deploy → verify → rollback
+```
+
+Cloudflare is the first complete implementation. Future VPS, GCP, and AWS
+providers must add a provider reference and adapter without changing the blog
+content, approval, URL, or SEO contracts. Read
+[provider-contract.md](references/provider-contract.md) when adding one.
+
+## Stop conditions
+
+Stop before deployment when the target is ambiguous, the domain is not
+confirmed, a production secret/binding is missing, migrations are not
+idempotent/backed up, the build target and runtime disagree, or verification
+cannot prove public/private route and indexability behavior.

package/bundled-skills/maggie-deployment/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maggie Deployment"
+  short_description: "Deploy Maggie blogs on Cloudflare Workers"
+  default_prompt: "Use Maggie deployment to inspect this project and prepare or execute a Cloudflare deployment."

package/bundled-skills/maggie-deployment/references/cloudflare.md

@@ -0,0 +1,76 @@
+# Cloudflare Workers deployment
+
+Use this guide when the user selects Cloudflare or when Cloudflare is the
+default for a new Maggie Astro deployment.
+
+## Target architecture
+
+```text
+Astro SSR → Cloudflare Worker
+                 ├─ D1: blog/content/ops state
+                 ├─ R2 or Images: originals and derivatives
+                 ├─ KV: cache/session/rate-limit state
+                 ├─ Secrets: AI CMO, email, analytics credentials
+                 └─ Cron/Workflows: scheduled pull, sitemap matching, reports
+```
+
+The Worker adapter supports on-demand rendered Astro routes. Use Wrangler as
+the source of truth for Worker configuration and bindings. The starter's
+`wrangler.jsonc` declares D1, R2, and KV binding names and separate staging and
+production environments; fill or provision resource IDs according to the
+chosen Cloudflare account before deploy.
+
+## Runtime compatibility gate
+
+The current local starter uses `better-sqlite3` and filesystem media writes.
+Those are Node development implementations, not Worker request implementations.
+Before a Cloudflare production build:
+
+1. select `MAGGIE_DEPLOY_PROVIDER=cloudflare`;
+2. use a D1-backed repository for all request-time content and Ops queries;
+3. use R2/Images or Cloudinary for media, with public delivery URLs stored in
+   `media_assets.delivery_url`;
+4. replace filesystem sessions/cache with KV or a supported Worker mechanism;
+5. keep migrations idempotent and run them separately with Wrangler;
+6. run the build and deployed verification against the Worker runtime.
+
+Do not hide a Node fallback behind a Cloudflare build. If the adapter is not
+ready, stop at the plan stage and report the exact blocking module/binding.
+
+## Commands
+
+From the Astro starter:
+
+```bash
+npm run build:cloudflare
+npx wrangler d1 migrations apply DB --local
+npx wrangler dev
+npx wrangler deploy --env staging
+npx wrangler deploy --env production
+```
+
+Build separately for each Cloudflare environment when using the Astro
+Cloudflare Vite integration. Verify staging before production and retain the
+previous Worker version for rollback.
+
+## Secrets and domains
+
+Set secrets with `wrangler secret put NAME --env staging` or the production
+equivalent. Only variable names belong in `.env.example` and `wrangler.jsonc`.
+Custom domains/routes must be confirmed before production deployment; a
+`workers.dev` URL is suitable for staging verification, not a replacement for
+the user's canonical domain.
+
+## Verification gate
+
+After deploy, check:
+
+- homepage and every published sitemap URL return expected status;
+- canonical, robots, Open Graph, Article JSON-LD, `datePublished`, and
+  `dateModified` point to the deployed host;
+- `/robots.txt` declares the correct sitemap and private Ops routes are not
+  indexable;
+- authenticated Ops/API routes reject unauthenticated requests;
+- D1 migration version, R2/media delivery, KV/session behavior, API Pull,
+  rewrite queue, and scheduled triggers are observable;
+- staging has no production analytics or email recipients.

package/bundled-skills/maggie-deployment/references/provider-contract.md

@@ -0,0 +1,32 @@
+# Deployment provider contract
+
+Deployment is a provider adapter, not a collection of vendor commands spread
+through blog code.
+
+Every provider must expose these phases:
+
+| Phase | Required result |
+|---|---|
+| `inspect` | target, runtime, bindings, secrets-by-name, and risks |
+| `plan` | explicit resource/migration/deploy plan with environment |
+| `provision` | resources created or existing IDs confirmed |
+| `migrate` | idempotent migration applied and recorded |
+| `build` | reproducible artifact for the selected runtime |
+| `deploy` | immutable commit/version and URL recorded |
+| `verify` | route, metadata, sitemap, robots, API and health checks |
+| `rollback` | known previous version and data rollback boundary |
+
+The provider must distinguish staging and production, never print secret
+values, and fail closed when a binding is absent. A provider may use a CLI or
+API, but the project keeps one declarative target manifest and one handover
+record.
+
+The application contract remains provider-neutral:
+
+- D1/Postgres/SQLite adapters implement the canonical content queries;
+- R2/Cloudflare Images/Cloudinary/local adapters implement media storage;
+- KV/Redis/database adapters implement cache/session needs;
+- email providers remain behind the existing email adapter.
+
+No provider-specific binding name belongs in post frontmatter, canonical URL
+logic, publication state, rewrite queue state, or sitemap generation.

package/bundled-skills/maggie-project-context/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: maggie-project-context
+description: Sync a site's safe AI CMO Project, selected brand voice, site settings, and CTA context into a local generated context file. Use when connecting a vibe-coded blog or existing website to AI CMO, refreshing brand context, or diagnosing missing CTA/project data.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Project Context
+
+Use the authenticated AI CMO Project as the source of truth for brand
+positioning, audience, voice, site URL, and conversion CTAs.
+
+## Workflow
+
+1. Inspect the host project and confirm where generated configuration belongs.
+2. Confirm `AI_CMO_API_KEY` is available server-side; never put it in browser
+   code, a committed file, logs, screenshots, or a public build.
+3. Run `python3 scripts/sync_ai_cmo_context.py` from this repository or use the
+   equivalent server-side request to `GET /project-context`.
+4. Keep the original `context` payload and consume the normalized `brand`,
+   `site`, and `conversion.ctas` views.
+5. Use `ETag`/`If-None-Match` for scheduled refreshes.
+6. Show a diff and request approval before changing public copy, links, or
+   publishing behavior.
+
+## Mapping
+
+```text
+project.products_services + project.usp -> product features
+project.target_audience + target_problem -> use cases
+brand_voice -> writing style
+project.cta.default_url -> conversion.ctas.default
+project.cta.other_urls -> conversion.ctas.additional
+```
+
+Do not export team, uploads, testimonials, market research, internal workflow
+state, API keys, or OAuth tokens into public source-of-truth files. Missing or
+stale context blocks automatic publishing and falls back to a preview.

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: maggie-seo-geo
+description: Plan, audit, create, rewrite, and measure content for AI CMO's paid SEO and GEO workflow. Use for topic opportunities, AI visibility, technical SEO, extractable article structure, sitemap-based rewrites, GSC readback, or SEO/GEO client reports.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie SEO and GEO
+
+Treat SEO and GEO as one measurable content system: people-first content,
+technical accessibility, extractable structure, evidence, authority, brand
+voice, CTA alignment, and observed search/AI outcomes.
+
+## Choose the mode
+
+- **Plan:** combine Project Context, GSC/search signals, competitor gaps, and
+  AI visibility prompts into topic clusters and briefs.
+- **Audit:** inspect robots, sitemap, canonical URLs, metadata, JSON-LD,
+  headings, links, author/freshness signals, and AI crawler access.
+- **Create/rewrite:** preserve the content identity and canonical URL; produce
+  a preview, run quality gates, then deliver only after approval.
+- **Measure:** distinguish retrieved, cited, mentioned, recommended, ranked,
+  clicked, and converted. Never convert a model suggestion into a metric.
+
+## AI CMO API Pull lifecycle
+
+```text
+project-context -> sitemap match -> rewrite queue -> updates -> local publish
+  -> report-state -> GSC/GA4/AI visibility readback
+```
+
+Use the API Pull integration contract for authentication, quota, retries,
+idempotency, and exact endpoint behavior. A sitemap URL is inventory evidence,
+not permission to overwrite a post: only explicitly matched/tracked assets may
+enter the rewrite queue.
+
+## Quality gate
+
+Before delivery, check:
+
+- search intent and topical coverage;
+- a direct answer and useful heading structure;
+- original evidence and links for material claims;
+- author, date, freshness, and transparent limitations;
+- Article/FAQ/HowTo/Product schema only where accurate;
+- canonical URL, slug, internal links, images and alt text;
+- AI crawler access without creating AI-only thin pages;
+- Project brand voice and CTA fidelity;
+- no unsupported rankings, traffic, citation, or conversion promises.
+
+Free audits and previews may run without generation. Paid generation,
+monitoring, rewriting, and recurring reports require the server entitlement
+and must stop cleanly on 401, 403, 429, or quota exhaustion.

package/bundled-skills/maggie-social-share/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: maggie-social-share
+description: Turn approved AI CMO articles and content assets into platform-native social drafts, scheduled posts, and measured distribution. Use for Social Share planning, LinkedIn/Facebook copy, CTA mapping, calendars, approvals, publish retries, or social performance readback.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Social Share
+
+Social Share is a distribution layer downstream of the same AI CMO Project,
+brand voice, CTA, canonical URL, content asset, and approval state used by SEO
+and GEO. It is not a second content source of truth.
+
+## Workflow
+
+1. Select an approved or explicitly shareable source article/content asset.
+2. Read Project Context and the selected social tone/template.
+3. Extract one clear content atom: insight, statistic, process, story, or
+   contrarian point. Do not invent proof absent from the source.
+4. Create platform-native variants with the platform's current limits and a
+   clear CTA. Preserve the source canonical URL and apply the configured UTM
+   policy.
+5. Store drafts as calendar items with source ID, platform, version, approval,
+   scheduled time, and local/remote status.
+6. Publish only after the required approval and entitlement checks. Record the
+   publication attempt and provider ID; retry only with bounded idempotency.
+7. Read back clicks, engagement, assisted conversions, and failures separately
+   from article SEO/GEO metrics.
+
+## Default output
+
+```text
+source_content_id, canonical_url, platform, format, hook, body, cta,
+hashtags_or_mentions, scheduled_at, approval_state, tracking_url
+```
+
+Start with LinkedIn and Facebook adapters. Add other platforms only when the
+adapter can declare limits, auth scope, media requirements, idempotency, and
+delete/republish behavior.
+
+## Safety and commercial boundary
+
+- A social draft is not a published post.
+- Never expose provider tokens or API CMO keys.
+- Do not make claims that are absent from approved source evidence.
+- Do not publish when the source article is unpublished, the CTA is missing, or
+  the server denies the paid feature.
+- Report provider failures without marking the item published.