@topy-ai/maggie 0.1.0

package/bundled-references/blog-operations-contract.md

@@ -0,0 +1,68 @@
+# Maggie Blog Operations Contract
+
+The starter keeps blog reading, content operations, migration, and agency
+administration on explicit server-side contracts. Agents may customize UI/UX,
+but must preserve these invariants:
+
+## Content operations
+
+- Every scheduled publication is stored in `content_calendar` and is promoted
+  only from an approved/review state by `POST /api/ops/calendar/publish-due`.
+- Every revision is a complete immutable post snapshot in `post_revisions`.
+- Every bulk mutation starts as `bulk-preview`; apply operations are limited to
+  an allowlist of fields and produce an `audit_events` record.
+- Redirects are unique by source path and accept only 301/308.
+- Media is a first-class `media_assets` record with usage counts, metadata and
+  optional folders; remote media is never silently assumed to be local.
+
+## Migration
+
+`POST /api/ops/migrations/import` accepts JSON, CSV, WXR, sitemap, or
+`media-archive` input in preview/apply mode. Imported content uses
+`source + source_id` as its identity and a SHA-256 checksum for incremental
+reruns. `syncMode` supports `all`, `new`, and `modified`; `detectDeleted` archives
+source records absent from a full snapshot, and `conflict` supports
+`source-wins`, `target-wins`, or `manual`. Redirect mappings support both JSON
+and CSV import/export. Persisted migrations can resume with
+`POST /api/ops/migrations/:id/resume`; source identity and checksums keep the
+resumed import idempotent. WordPress REST remains the richer adapter for terms,
+authors, featured media and old-path redirects.
+
+## Agency
+
+`workspaces`, `clients`, `sites`, and `workspace_members` isolate client data
+and credentials. Workspace-scoped reads and writes use `/api/ops/agency` and
+reject cross-workspace client/site/project relations. Roles are fixed to the
+eight supported agency roles; secrets remain in server
+environment/configuration and are never returned by browser APIs.
+`approval_links` provides expiring, branded-review-compatible handoff tokens
+without storing raw tokens.
+
+Entity profiles and `entity_relations` form a small explicit entity graph;
+insights also return refresh recommendations derived from persisted content
+quality signals rather than silently mutating published content.
+
+## Vibe-coding safety
+
+Bootstrap confirmation writes the project, decisions, schema, routes,
+integrations, and migration manifests under `.maggie/`. `maggie doctor` and
+`npm run schema:check` are required gates before generated code is considered
+ready. Fixtures are deterministic and must be used for local provider tests.
+
+## API Pull lifecycle
+
+The adapter exposes project context, post/update pulls, sitemap matching
+history, rewrite queue/history, and publication-state reporting as separate
+server-only operations. A local write and approval decision must complete
+before `report-state` is called. Batch reporting is bounded to 500 records per
+request, and API credentials are read from server configuration only.
+
+## External providers
+
+Email and media are provider-neutral contracts. Resend is the default email
+adapter and Cloudinary is the default media storage/delivery adapter; local or
+webhook adapters can be selected without changing post, report, or media
+records. Provider adapters must expose configuration health, normalize errors,
+and never return credentials through Ops APIs. A new provider should implement
+the relevant interface and register its ID rather than adding provider fields
+to content templates.

package/bundled-references/browser-inspection.md

@@ -0,0 +1,39 @@
+# Maggie Clone Browser Inspection Contract
+
+`maggie-clone` requires an available browser automation capability. The skill
+is intentionally provider-neutral: use the configured Chrome, browser,
+Playwright, Puppeteer, or equivalent MCP tools rather than adding a fake local
+MCP server to the host project.
+
+The browser capability must support:
+
+- navigation to a target URL and reading the final URL after redirects;
+- desktop, tablet, and mobile viewport sizes;
+- full-page and viewport screenshots saved to the planned artifact directory;
+- DOM/text/attribute queries and JavaScript evaluation;
+- slow scrolling, click, hover, keyboard focus, and back/forward navigation;
+- reading computed CSS, media sources, links, and visible accessibility labels.
+
+The minimum extraction result for a target is:
+
+```text
+final URL and redirect chain
+viewport screenshots: 1440, 768, 390
+page sections and destination route
+visible copy and links
+computed design tokens
+asset URLs and media metadata
+interaction states and triggers
+responsive differences
+```
+
+If a target requires login, a bot challenge, a consent interaction, or a
+private browser profile, stop at that boundary and ask the user to provide
+authorized access. Do not bypass access controls or record cookies in project
+artifacts.
+
+Use browser evaluation to measure values; do not infer a Tailwind class from
+appearance. For every stateful component capture state A and state B and
+record the trigger and transition. Keep screenshots and extracted data under
+the target's namespaced research root so multiple URLs cannot overwrite one
+another.

package/bundled-references/provider-adapter-contract.md

@@ -0,0 +1,68 @@
+# Maggie Provider Adapter Contract
+
+Third-party services are implementation details behind stable interfaces. Blog
+routes, content records, reports, and Ops screens must depend on capabilities,
+not on a vendor SDK or vendor-specific fields.
+
+## Defaults
+
+| Capability | Default | Local/development alternative |
+|---|---|---|
+| Email delivery | `resend` | `webhook` or `disabled` |
+| Media storage and delivery | `cloudinary` | `local` |
+
+The default can be changed through environment configuration. Missing
+credentials fail closed: email is queued or reports a provider error, and
+media upload is marked failed. A typo or unknown provider never silently falls
+back to a different external service.
+
+## Email interface
+
+An email adapter implements `EmailProvider`:
+
+```ts
+type EmailProvider = {
+  id: string;
+  send(message: EmailMessage): Promise<EmailResult>;
+  health(): { configured: boolean; capabilities: string[]; reason?: string };
+};
+```
+
+`EmailMessage` contains only normalized `from`, `to`, `subject`, `html`,
+optional `text`, and optional `replyTo`. The Resend adapter uses the server-only
+`RESEND_API_KEY` and `EMAIL_FROM`; it never accepts credentials from a request.
+The webhook adapter preserves compatibility with existing mail gateways.
+
+## Media interface
+
+An image/video/file adapter implements `MediaStorageProvider`:
+
+```ts
+type MediaStorageProvider = {
+  id: string;
+  upload(input: MediaUpload): Promise<MediaUploadResult>;
+  health(): { configured: boolean; capabilities: string[]; reason?: string };
+};
+```
+
+The normalized result stores provider ID, storage key, delivery URL, byte
+count, and MIME type. Local adapters may additionally return a filesystem path;
+public delivery URL and local path must not be conflated. Cloudinary uploads
+are signed server-side and expose only the resulting delivery URL to public
+rendering.
+
+## Adding a provider
+
+1. Implement the relevant interface in `src/lib/providers/`.
+2. Normalize provider errors into `sent`, `queued`, `failed`, or upload failure
+   states; include a bounded, non-secret error message.
+3. Implement `health()` with capabilities and required configuration names.
+4. Register the adapter with `registerEmailProvider()` or
+   `registerMediaStorageProvider()`.
+5. Add env names to `.env.example`, but never add values or credentials to
+   generated files, logs, database settings, or browser bundles.
+6. Add a fixture/mock and a contract test for missing credentials, success,
+   retryable failure, and idempotent repeated calls.
+
+Provider-specific options belong in provider configuration, not in the
+canonical post or report schema.

package/bundled-references/seo-technical-contract.md

@@ -0,0 +1,75 @@
+# Maggie SEO Technical Contract
+
+This contract fixes the SEO output that agents should generate. Layout and
+visual design remain flexible; these page-level signals are not optional.
+
+## Required post metadata
+
+Every published post response should contain exactly one of each where
+applicable:
+
+```text
+<title>{title} | {site name}</title>
+<meta name="description" content="{excerpt}">
+<link rel="canonical" href="{absolute canonical URL}">
+<meta property="og:type" content="article">
+<meta property="og:title" content="{title}">
+<meta property="og:description" content="{excerpt}">
+<meta property="og:url" content="{absolute canonical URL}">
+<meta property="og:image" content="{absolute image URL}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="{title}">
+<meta name="twitter:description" content="{excerpt}">
+```
+
+Rules:
+
+- Escape all values for HTML attributes and JSON-LD.
+- Use the configured site origin; never derive canonical URLs from an
+  untrusted `Host` header.
+- Do not index preview, query-string, draft, login, or error URLs.
+- Do not emit empty descriptions, relative canonical URLs, or placeholder image
+  URLs.
+- A post page has one visible `h1`; headings in body content start at `h2`.
+
+## Article JSON-LD
+
+Emit one `Article` or `BlogPosting` object that agrees with visible content:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Post title",
+  "description": "Post excerpt",
+  "mainEntityOfPage": { "@type": "WebPage", "@id": "https://example.com/posts/post-title" },
+  "url": "https://example.com/posts/post-title",
+  "datePublished": "2026-08-28T00:00:00Z",
+  "dateModified": "2026-08-28T00:00:00Z",
+  "author": { "@type": "Person", "name": "Author" },
+  "publisher": { "@type": "Organization", "name": "Site name" },
+  "image": ["https://example.com/images/post-title.jpg"]
+}
+```
+
+Never invent an author, date, publisher, review, rating, or image. Omit an
+optional property when the source does not provide it. JSON-LD must not claim
+facts that are absent from the rendered page.
+
+## Crawl surfaces
+
+`robots.txt` must be a successful plain-text response and reference the
+absolute sitemap URL. The sitemap must:
+
+- contain only canonical, published post URLs;
+- use valid XML and an absolute `<loc>`;
+- include `<lastmod>` only when it is a trustworthy ISO date;
+- exclude drafts, redirects, duplicates, unmatched records, and query URLs;
+- use a sitemap index when the output exceeds the chosen URL limit.
+
+## Acceptance checks
+
+The adapter or CLI should fail the build or preview check when a published
+post has a missing title, slug, canonical URL, publication date, metadata,
+JSON-LD, or sitemap eligibility decision. Also test a draft, an unpublished
+post, a missing slug, a changed slug with redirect, and a failed content sync.

package/bundled-skills/README.md

@@ -0,0 +1,16 @@
+# Maggie Skills Index
+
+Skills are the agent-facing workflows. They compose with the tools in
+`../tools/REGISTRY.md` and the portable host templates in `../templates/`.
+
+| Skill | Primary job | Dependencies |
+|---|---|---|
+| `maggie-blog-bootstrap` | Build a complete blog in an existing project | site audit, analytics, API Pull |
+| `maggie-clone` | Reverse-engineer authorized URLs into namespaced blog-project pages | browser MCP, clone planner CLI, bootstrap state |
+| `maggie-deployment` | Deploy and verify a dynamic Maggie blog, Cloudflare-first | Cloudflare Workers, D1, R2, KV, Wrangler |
+| `maggie-project-context` | Sync Project, voice, site and CTA context | project-context CLI/API |
+| `maggie-seo-geo` | Plan, audit, create/rewrite and measure SEO/GEO | visibility, SEO audit, GSC/GA4, content quality |
+| `maggie-social-share` | Repurpose and distribute approved content | Project Context, social adapter, analytics |
+
+Read only the selected skill and its linked references for a task. Do not load
+all skills as one undifferentiated prompt.

package/bundled-skills/maggie-blog-bootstrap/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: maggie-blog-bootstrap
+description: Build or complete a small SEO/GEO-ready blog in an existing vibe-coded project, including posts, metadata, sitemap, analytics hooks, and optional AI CMO API Pull integration. Use when adding a blog to a custom site, WordPress, Wix, Shopify, or headless stack.
+metadata:
+  version: 1.3.0
+---
+
+# Maggie Blog Bootstrap
+
+Build or complete a small production blog inside an existing vibe-coded
+project. This skill is for Codex, Claude Code, and compatible coding agents.
+
+## Trigger
+
+Use when the user asks to add a blog, posts listing, post pages, sitemap, SEO,
+GA4/GSC, AI CMO API Pull, rewrite delivery, or a basic content system.
+
+## Operating rules
+
+1. Analyze the codebase before proposing a stack or editing files. Every
+   recommendation must cite the file, configuration, dependency, or command
+   output that supports it.
+2. Preserve existing conventions. Do not replace a working UI system, icon set,
+   font, database, CMS, router, or analytics implementation merely because a
+   default is available.
+3. Separate read-only inspection, recommendation, implementation, external
+   write, publish, and measurement actions.
+4. Keep all credentials in environment variables. Add `.env.example`, never
+   real values.
+5. Ask for confirmation at the decision gates below. A user saying “build a
+   blog” is not approval to select an unconfirmed database, visual identity,
+   language, or publishing policy.
+6. Prefer deterministic adapters and idempotent upserts over one-off scripts.
+
+## Required phases
+
+### Phase 1: Codebase analysis
+
+This is the most important phase. It is read-only unless the user explicitly
+asks for a fix. Search the whole project, not only the obvious `src/` folder,
+and produce an evidence-backed report covering:
+
+- framework, language, package manager, router, build command, runtime, and
+  deployment target;
+- user-facing language(s), locale, date/number conventions, and whether the
+  existing copy is English, Traditional Chinese, Simplified Chinese, or
+  multilingual;
+- UI system: Tailwind, CSS Modules, plain CSS, MUI, shadcn, Chakra, existing
+  component library, design tokens, spacing scale, and responsive conventions;
+- icon system: Heroicons, Lucide, Font Awesome, custom SVGs, icon package
+  dependencies, and whether icons are used consistently;
+- typography: imported/local fonts, `@font-face`, Google Fonts, CSS variables,
+  font weights, fallback stack, and whether the current font should be kept;
+- database: engine, connection configuration, ORM/query layer, schema/migrations,
+  hosting, environment variables, seed data, and existing post/content tables;
+- content source: Markdown/MDX, database, CMS, API, JSON, hardcoded data, or
+  no existing source; include slug/title/status fields and ownership boundaries;
+- existing `/robots.txt`, `/sitemap.xml`, metadata, JSON-LD, GA4, GSC, auth,
+  server/runtime boundaries, and API-key safety;
+- tests, lint/typecheck commands, CI, preview command, and production deploy
+  command.
+
+Also produce three migration-safety inventories inspired by the website build
+kit workflow:
+
+- a route inventory separating public routes from API/Ops/admin routes;
+- a preservation inventory for redirects, robots, sitemap, RSS, verification,
+  favicon/brand, social-image, and security-header assets;
+- a reproducibility inventory of dev, build, test, lint/typecheck, preview, and
+  deploy commands, including the command that must run before handover.
+
+These inventories are evidence, not permission to edit. A missing build gate,
+unknown runtime, or route with unclear public/private ownership becomes an
+explicit risk and decision gate.
+
+Use targeted searches such as `package.json`, lockfiles, `src/`, `app/`,
+`pages/`, `server/`, `prisma/`, `drizzle/`, migration folders, CSS files,
+font files, SVG/icon imports, `.env.example`, and deployment configuration.
+Never print secret values. Report variable names and whether they are present,
+missing, or referenced only.
+
+The report must distinguish:
+
+```text
+Detected       confirmed by code or configuration
+Likely         supported by multiple clues but not definitive
+Missing        required for the proposed implementation but not found
+Unknown        cannot be determined safely from the repository
+```
+
+Use this compact report shape so the user can review the evidence before any
+implementation starts:
+
+```text
+Codebase analysis
+- Framework/runtime: [status] ... (evidence: path or command)
+- Project language: [status] ...
+- Content language/locale: [status] ...
+- UI system: [status] ...
+- Icon set: [status] ...
+- Font/typography: [status] ...
+- Database/ORM/schema: [status] ...
+- Content source/post model: [status] ...
+- SEO/analytics/deployment: [status] ...
+
+Maggie's recommendation
+- Primary plan: ...
+- Alternatives: ...
+- What will not change: ...
+- Decisions requiring confirmation: ...
+- Risks or unknowns: ...
+```
+
+Do not call a dependency “detected” only because it appears in a lockfile;
+confirm that it is used by the running application or relevant route. Do not
+call a database “available” only because an environment variable is named;
+inspect the connection code and schema/migration usage without revealing its
+value.
+
+### Phase 2: Recommendation
+
+After the inventory, propose one primary plan and at most two alternatives.
+Explain the trade-offs and cite the evidence. Cover each decision separately:
+
+| Decision | Recommendation requirement |
+|---|---|
+| Framework | Keep the detected framework; choose one only if the project is empty or the user requests a migration |
+| Programming language | Keep detected TypeScript/JavaScript and conventions |
+| Content language | Infer from existing copy, then confirm the default language and future locales |
+| UI system | Reuse the detected system; default to Tailwind only when no coherent system exists |
+| Icon set | Reuse the detected set; default to Heroicons when using Tailwind and no set exists |
+| Font | Reuse the detected font; otherwise propose a small accessible system stack and ask before adding a web font |
+| Database | Reuse the detected engine and ORM; default to SQLite only for a genuinely new small single-instance project |
+| Production database | Do not assume SQLite is suitable for multi-instance/serverless production; propose the smallest supported hosted database and confirm it |
+| Content source | Prefer the existing source; create a minimal posts table or local content collection only after approval |
+| Deployment | Preserve the existing target and server/runtime boundaries |
+
+The recommendation must include a “what will not change” section. If the
+database, language, or visual system is unknown, say so instead of guessing.
+
+### Phase 3: Decision gates
+
+Ask the user to confirm the recommendation in small groups before writing code:
+
+1. **Foundation:** framework, programming language, content language, runtime,
+   and deployment target.
+2. **Experience:** UI system, icon set, font, theme, and accessibility baseline.
+3. **Data:** database engine, ORM, migrations, content source, post fields,
+   ownership, and local-vs-production storage.
+4. **Content and publishing:** initial routes, API Pull, sitemap matching,
+   rewrite approval, analytics, GSC, and whether the first run is dry-run.
+
+Show the proposed choices, detected evidence, files likely to change, and
+unknowns for each gate. If the user confirms only part of a gate, implement
+only that part and leave the rest pending. Do not ask a single broad “is this
+okay?” question that hides database or publishing choices.
+
+Recommended defaults for a new, small project are:
+
+```text
+Tailwind CSS        UI foundation
+Heroicons           icons when no existing icon set is present
+system font stack   font unless the user approves a web font
+SQLite              local/single-instance development and deployment only
+TypeScript          when the selected framework already supports it cleanly
+English             only when existing project language is absent
+```
+
+These are proposals, not automatic permission. SQLite, English, a new font,
+or a new design system must never silently replace detected project choices.
+
+### Phase 4: Contract
+
+Implement or map these post fields:
+
+```text
+id, slug, title, excerpt, content, publishedAt, updatedAt,
+canonicalUrl, coverImage, author, tags, status
+```
+
+The public contract must support:
+
+- `/posts` with stable pagination or a bounded list;
+- `/posts/:slug` with a real 404 for missing/unpublished posts;
+- canonical, Open Graph, Twitter, and Article metadata;
+- post links that are crawlable plain anchors;
+- `robots.txt` and a post-only sitemap;
+- a stable, server-rendered or statically generated reading path.
+
+### Phase 5: Build
+
+Implement the host project's equivalent of:
+
+- posts index with title, excerpt, date, image, and accessible links;
+- post detail with heading hierarchy, readable content, related posts where
+  justified, and visible updated date;
+- sitemap URL generation from published posts only;
+- canonical URL normalization without duplicate slash/query variants;
+- JSON-LD `Article` or `BlogPosting` with valid dates and image URLs;
+- GA4 page view/event hooks that do nothing when analytics is disabled;
+- GSC verification via a public token or DNS instruction, never a private key.
+
+### Phase 6: Optional AI CMO integration
+
+Only when requested and configured, add the adapter described in
+`tools/integrations/maggie-api-pull.md`. It must:
+
+- resolve the domain from the API key, not from user input;
+- poll `/posts` and `/updates` on a schedule;
+- upsert by remote content id and preserve the remote canonical URL;
+- never change a slug during rewrite;
+- store delivery state and last error;
+- expose a dry-run/import preview before first publish;
+- report successful local publication with `report-state`.
+- sync the sanitized `/project-context` response into a generated local file;
+  map its project CTA into the portable starter's `conversion.ctas` fields.
+
+### Phase 7: Verify
+
+Run `python3 tools/clis/site_audit.py <production-url> --json` and host-project
+tests. Manually verify:
+
+```text
+/posts
+/posts/<known-slug>
+/posts/<missing-slug> -> 404
+/robots.txt
+/sitemap.xml
+analytics disabled -> no crash and no analytics request
+```
+
+Report known limitations, especially if the project is client-rendered,
+requires authentication for content, or has no stable post database.
+
+## Completion contract
+
+Finish with:
+
+- files changed and why;
+- commands/tests run;
+- environment variables added, by name only;
+- whether publishing and API Pull are enabled or still dry-run;
+- remaining risks and the next safe action.