@topy-ai/maggie 0.7.33 → 0.7.35

package/README-zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.33 init --agent all
+npx @topy-ai/maggie@0.7.35 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,7 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 release 是 `0.7.33`，記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 release 是 `0.7.35`，完成下一批已驗證 feedback：production fixture isolation、MaggieDash project-id inference、responsive/background asset extraction、穩定 SEO structure hash、decorative alt、明確 site URL/build validation、真正 404、Tailwind v4 starter、portable CLI scripts，以及不含 local dependencies/cache 的 Astro starter bundle。延後功能記錄在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -60,7 +60,16 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 19 installable skills and a local-first MaggieDash foundation.
 
-The current release is `0.7.33`. It records the reviewed correction for the
+The current release is `0.7.35`. It closes the next validated feedback batch:
+production demo fixtures are development-only, Dash infers the persisted
+project id, clone asset extraction includes responsive/background assets, SEO
+structure hashes ignore content-hashed asset names, decorative empty alt text
+is accepted, and missing starter routes return a real 404. It also adds a
+Tailwind v4 starter entry point, explicit `PUBLIC_SITE_URL` validation, a
+portable installed-CLI script path, and a bundled Astro starter without local
+dependencies or build caches. Deferred feature requests are tracked in
+[issue #38](https://github.com/TOPY-AI-LTD/ai-cmo-skills/issues/38), not active
+memory. The 0.7.33 release records the reviewed correction for the
 batch-index feedback workflow while keeping the verified 0.7.32 behavior
 unchanged. The 0.7.32 release added explicit one-based feedback batch index
 support, source/freshness/error evidence for MaggieDash measurement
@@ -500,8 +509,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.33 update --project . --force
-npx @topy-ai/maggie@0.7.33 cleanup --project .
+npx @topy-ai/maggie@0.7.35 update --project . --force
+npx @topy-ai/maggie@0.7.35 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -774,6 +783,10 @@ report. It fails closed when source evidence is missing unless
 The marketplace catalog is lightweight and templates are fetched on demand.
 These desktop previews are hosted by the public NoBlox template registry so
 the npm package does not download every template asset during installation.
+The package also includes the small, dependency-free Astro blog starter under
+`bundled-templates/astro-blog/starter`; run `npm install` in the copied starter
+and configure `PUBLIC_SITE_URL` before building. Its Tailwind v4 entry point is
+opt-in at the host project level, and production never falls back to demo posts.
 
 <table>
   <tr>

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

@@ -68,6 +68,14 @@ response fields. It does not accept a static source scan as runtime evidence.
 
 - Preserve detected framework, language, router, UI system, icon set, fonts,
   database, and deployment target unless the user confirms a change.
+- The bundled Astro starter is SQLite-first. A PostgreSQL or MySQL selection is
+  only a host adapter decision until the project provides and verifies its
+  repository/migration adapter; never report the starter's SQLite store as a
+  working PostgreSQL adapter.
+- An empty directory still needs an approved host framework scaffold. Do not
+  pretend that installing Maggie skills alone creates an Astro/Next.js app;
+  use the bundled starter or the host framework's official scaffold, then run
+  the interview against that project.
 - Store no credentials in source or `.maggie` reports. API keys stay server
   side and are never inferred from a domain.
 - Traditional email/password auth uses the MaggieDash auth contract; passkeys,

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

@@ -152,7 +152,8 @@ interaction states, and component specs. Capture desktop (1440px), tablet
 - 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;
+- every image, responsive `srcset` candidate, CSS/inline background, video,
+  SVG, favicon, font, 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
@@ -164,6 +165,11 @@ 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.
 
+Headless browser tabs can throttle timers in the background. Wait for
+Lenis/ScrollTrigger-style smooth scrolling and animations to settle before
+capturing; record the settle method, such as a stable `animation.currentTime`,
+in the evidence notes.
+
 Persist the evidence before building:
 
 ```text

package/bundled-templates/astro-blog/README.md

@@ -0,0 +1,217 @@
+# Astro Blog Template Contract
+
+This is a Maggie implementation contract for an existing Astro project. It is
+not a second starter app: inspect the host project first, preserve its layout,
+styling, deployment adapter, and content source, then add only the missing blog
+surfaces.
+
+Astro is the preferred template for content-heavy sites. Use Content
+Collections for local or build-time content, and use a live loader or server
+endpoint only when the product requires request-time freshness. Astro defaults
+to static output and hydrates interactive components as islands, so keep the
+blog reading path mostly server-rendered HTML.
+
+See the shared [blog implementation contract](../../bundled-references/blog-implementation.md)
+and [canonical data contract](../../bundled-references/blog-data-contract.md) for the
+stable backend model. Use the [technical SEO contract](../../bundled-references/seo-technical-contract.md)
+for behaviour and acceptance criteria. For AI CMO-specific work, read the
+[Maggie API Pull guide](../../bundled-tools/integrations/maggie-api-pull.md) and
+[Maggie Project Context guide](../../bundled-tools/integrations/maggie-project-context.md).
+The complete public-page and private-operations surface is defined in the
+[AI-native blog application contract](../../bundled-references/ai-native-blog-contract.md).
+The daily operations data model and API are defined in the
+[blog operations contract](../../bundled-references/blog-operations-contract.md).
+For deployment, use the [Maggie Deployment skill](../../bundled-skills/maggie-deployment/SKILL.md);
+the starter includes a Cloudflare Workers target with D1, R2, KV, and Wrangler
+configuration. Keep Node/SQLite for local development only until the D1
+repository boundary is selected and verified.
+
+## Expected mapping
+
+Adapt names to the host project, but preserve these responsibilities:
+
+```text
+src/content.config.ts              typed post collection and schema
+src/content/posts/                 local Markdown/MDX posts, if used
+src/pages/posts/index.astro        crawlable post list
+src/pages/posts/[...slug].astro    post detail and 404 handling
+src/pages/sitemap-index.xml.ts     sitemap index when multiple sitemaps exist
+src/pages/sitemap-0.xml.ts         published post URLs and lastmod
+src/pages/robots.txt.ts            crawler rules and sitemap reference
+src/layouts/PostLayout.astro       metadata, JSON-LD, and article shell
+src/lib/posts.ts                   source adapter and read model
+src/components/analytics/GA4.astro consent-aware analytics hook
+```
+
+The [`examples/`](examples/) directory contains a Content Collections schema,
+typed config, route manifest, metadata builder, and Ops transition guard. Treat
+them as typed starting points, not permission to change the canonical field
+names.
+
+The actual sitemap route may be provided by an Astro integration. Do not
+create duplicate sitemap routes; verify the generated response instead.
+
+The default list configuration is `postsPerPage: 9` and `gridColumns: 3`,
+rendering a 3×3 grid. The starter exposes these as
+`PUBLIC_POSTS_PER_PAGE` and `PUBLIC_GRID_COLUMNS`; operators can change them
+later through the typed site-settings boundary.
+
+Keep these stable: the post model, publication state, source identity, URL
+rules, metadata fields, JSON-LD semantics, sitemap eligibility, and sync/error
+state. Let the agent choose the visual layout, component composition, colors,
+spacing, and interaction details after it has detected the existing design
+system.
+
+The Maggie Ops starter uses a CMS-style operator journey: persistent workspace
+navigation, a compact account bar, dashboard-first summary metrics, quick next
+actions, visible health status, and responsive navigation on small screens. It
+keeps Maggie's content, API Pull, sitemap, rewrite, SEO/GEO, and agency flows
+inside this shell without depending on another CMS.
+
+## Required frontend surface
+
+Implement the public information architecture from the shared application
+contract:
+
+```text
+/blog                         title, description, hot topics, grid, FAQs, CTA, pagination
+/blog/[slug]                  EEAT authorship, dates, content, related posts, FAQs, CTA
+/topics                       topic index
+/topics/[topic-slug]          topic title, description, post grid, FAQs, CTA, pagination
+/authors/[author-slug]        authorship and published posts, when enabled
+/sitemap.xml                  published canonical URLs only
+/robots.txt                   crawler policy and sitemap reference
+```
+
+The agent may design the header, cards, navigation, typography, color system,
+responsive layout, and progressive enhancement. It must use the shared
+repository functions for publication filtering and the shared metadata builder
+for SEO output.
+
+## Maggie Ops surface
+
+Bootstrap must ship the complete private dashboard described in the shared
+[Ops dashboard contract](../../bundled-references/ops-dashboard-contract.md). The
+starter's `src/pages/ops/` and `src/pages/api/ops/` are the reference
+implementation; preserve their authentication and repository boundaries when
+customizing the UI.
+
+Implement `/ops` as a private authenticated application, never as a public
+content route. The minimum screens are:
+
+```text
+/ops                         health, sync state, queue, and recent reports
+/ops/posts                   inventory, filters, status, and bulk-safe actions
+/ops/posts/[id]/edit         validated post edit and metadata preview
+/ops/posts/[id]/preview      noindex preview with draft/review state
+/ops/topics                  topic, FAQ, and published-post management
+/ops/sitemap                 sitemap sources, matching history, eligibility
+/ops/reports                 technical SEO, content quality, visibility, analytics
+/ops/settings/site           origin, locale, timezone, defaults, CTA
+/ops/settings/integrations   AI CMO, GSC, and GA4 configured/verified status
+/ops/wordpress                WordPress preview, apply, resume, and import history
+```
+
+All writes require authentication, authorization, an audit event, and a
+visible confirmation. Publishing, rewrite queueing, sitemap matching, and
+integration changes must show a dry-run or impact preview first.
+
+WordPress migration is an explicit server-side workflow. It reads the
+WordPress REST API posts, categories, tags, and media collections; preserves
+source IDs for idempotent reruns; maps categories to draft topics; stores tags
+as migration terms; registers featured/all media; and records old-path
+redirects. Imported posts are drafts unless the operator explicitly selects
+the preserve-published option. See the [Astro starter migration screen](starter/README.md)
+for environment and operation details.
+
+## Content model
+
+Define a single normalized post shape at the adapter boundary. The full
+database, sync-state, delivery-state, redirect, and metadata contracts live in
+the shared references:
+
+- [blog data contract](../../bundled-references/blog-data-contract.md)
+- [technical SEO contract](../../bundled-references/seo-technical-contract.md)
+
+The Astro-specific schema starts here:
+
+```ts
+type Post = {
+  id: string
+  slug: string
+  title: string
+  excerpt?: string
+  content: string
+  publishedAt: string
+  updatedAt?: string
+  canonicalUrl?: string
+  coverImage?: string
+  author?: { name: string; url?: string }
+  status: "draft" | "review" | "approved" | "scheduled" | "published" | "archived"
+}
+```
+
+Use the [example Content Collections schema](examples/content.config.ts) for
+local or build-time entries. If the
+remote API has optional or inconsistent fields, normalize and validate them in
+`src/lib/posts.ts`; do not spread provider-specific fields through templates.
+The `slug` is the public identity and must not silently change after
+publication. Create a redirect when a published slug must change.
+
+## Rendering and data freshness
+
+- Prefer prerendered post pages for stable content and CDN delivery.
+- Use `getStaticPaths()` for build-time collections and ensure unpublished
+  entries never produce a public route.
+- For API Pull content that changes without a deploy, choose an Astro server
+  adapter and fetch through a server-only module, or trigger a controlled
+  rebuild after a successful sync.
+- Keep API keys in server-only environment variables. Never expose them through
+  `PUBLIC_*`, client islands, serialized page props, or browser requests.
+- Cache remote reads and make sync jobs idempotent. A build failure must not
+  replace the last known-good public content with an empty collection.
+
+## API Pull and rewrite boundary
+
+The Astro site is a host adapter, not the rewrite source of truth:
+
+1. Fetch published or explicitly requested posts from Maggie API Pull.
+2. Map remote identifiers, title, slug, canonical URL, timestamps, and body
+   into the local `Post` model.
+3. Store a stable remote ID and sync cursor so retries do not duplicate posts.
+4. Treat sitemap matching as an explicit queue input; match by canonical URL or
+   normalized slug, then title-derived slug only when the existing slug is
+   empty and the result is unique.
+5. Pull rewrite results into a draft or review state. Do not publish from a
+   build hook, cron job, or content loader without an explicit approval gate.
+
+The sitemap must contain only posts that are public on the host site, with
+absolute canonical URLs and `lastmod` when known.
+
+## SEO, GEO, and analytics requirements
+
+Each post page should server-render:
+
+- one `h1`, title, author, published date, and primary content;
+- canonical URL, description, Open Graph, and Twitter metadata;
+- Article JSON-LD that agrees with visible content;
+- useful internal links and image dimensions/alt text;
+- no indexable duplicate query URLs.
+
+Add GA4 only when configured and permitted by the site's consent policy. Add
+GSC verification through an environment variable, HTML file, or DNS workflow;
+do not hardcode ownership tokens in the template.
+
+## Acceptance checklist
+
+```bash
+npm run build
+npm run preview
+```
+
+Verify the rendered list, a post, an unpublished/missing post, `robots.txt`,
+the sitemap, canonical metadata, JSON-LD, analytics-disabled mode, and an API
+Pull failure with a preserved last-known-good build.
+
+The [local site audit](../../bundled-tools/clis/site_audit.py) can check the deployed
+host, but it does not replace route-level tests.

package/bundled-templates/astro-blog/examples/blog.config.ts

@@ -0,0 +1,30 @@
+export const blogConfig = {
+  site: {
+    name: "Example Site",
+    baseUrl: "https://example.com",
+    locale: "en-GB",
+    timezone: "Europe/London",
+    blogPath: "/blog",
+    postsPerPage: 12,
+    topicMinimumPosts: 3,
+  },
+  defaults: {
+    language: "en",
+    robotsPolicy: "index,follow",
+  },
+  integrations: {
+    aiCmo: {
+      enabled: false,
+      baseUrl: "https://api.cmo.so",
+      apiKeyEnv: "AI_CMO_API_KEY",
+      syncMode: "manual",
+    },
+    gsc: { enabled: false, verificationMode: "dns" },
+    ga4: { enabled: false, consentRequired: true },
+  },
+  publishing: {
+    requireApproval: true,
+    allowScheduledPublish: false,
+    allowAutoRewritePublish: false,
+  },
+} as const;

package/bundled-templates/astro-blog/examples/content.config.ts

@@ -0,0 +1,28 @@
+import { defineCollection, z } from "astro:content";
+import { glob } from "astro/loaders";
+
+const posts = defineCollection({
+  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/posts" }),
+  schema: z.object({
+    id: z.string(),
+    source: z.enum(["local", "api-pull", "cms", "manual"]),
+    sourceId: z.string().optional(),
+    title: z.string().min(1),
+    excerpt: z.string().default(""),
+    canonicalUrl: z.string().url(),
+    coverImageUrl: z.string().url().optional(),
+    coverImageAlt: z.string().optional(),
+    authorName: z.string().optional(),
+    authorUrl: z.string().url().optional(),
+    language: z.string().default("en"),
+    tags: z.array(z.string()).default([]),
+    status: z.enum(["draft", "review", "approved", "scheduled", "published", "archived"]),
+    publishedAt: z.coerce.date().optional(),
+    updatedAt: z.coerce.date().optional(),
+  }).refine(
+    (post) => post.status !== "published" || post.publishedAt !== undefined,
+    "published posts require publishedAt",
+  ),
+});
+
+export const collections = { posts };

package/bundled-templates/astro-blog/examples/metadata.ts

@@ -0,0 +1,37 @@
+type PostMeta = {
+  title: string;
+  excerpt: string;
+  canonicalUrl: string;
+  imageUrl?: string;
+  authorName?: string;
+  publishedAt: string;
+  updatedAt?: string;
+};
+
+export function buildPostMeta(post: PostMeta, siteName: string) {
+  const image = post.imageUrl ? [post.imageUrl] : undefined;
+  return {
+    title: `${post.title} | ${siteName}`,
+    description: post.excerpt,
+    canonical: post.canonicalUrl,
+    openGraph: {
+      type: "article",
+      title: post.title,
+      description: post.excerpt,
+      url: post.canonicalUrl,
+      images: image,
+    },
+    twitter: { card: "summary_large_image", title: post.title, description: post.excerpt, images: image },
+    jsonLd: {
+      "@context": "https://schema.org",
+      "@type": "Article",
+      headline: post.title,
+      description: post.excerpt,
+      url: post.canonicalUrl,
+      datePublished: post.publishedAt,
+      ...(post.updatedAt ? { dateModified: post.updatedAt } : {}),
+      ...(post.authorName ? { author: { "@type": "Person", name: post.authorName } } : {}),
+      ...(image ? { image } : {}),
+    },
+  };
+}

package/bundled-templates/astro-blog/examples/ops-api.ts

@@ -0,0 +1,31 @@
+type PostState = "draft" | "review" | "approved" | "published" | "archived";
+
+const transitions: Record<PostState, PostState[]> = {
+  draft: ["review", "archived"],
+  review: ["draft", "approved", "archived"],
+  approved: ["review", "published", "archived"],
+  published: ["archived"],
+  archived: ["draft"],
+};
+
+export function assertPostTransition(from: PostState, to: PostState) {
+  if (!transitions[from].includes(to)) {
+    throw new Error(`invalid post transition: ${from} -> ${to}`);
+  }
+}
+
+export function assertPublishable(post: {
+  status: PostState;
+  title: string;
+  slug: string;
+  canonicalUrl: string;
+  publishedAt?: string;
+  authorId?: string;
+  topicIds: string[];
+}) {
+  if (post.status !== "approved") throw new Error("post must be approved before publishing");
+  if (!post.title || !post.slug || !post.canonicalUrl) throw new Error("post SEO identity is incomplete");
+  if (!post.authorId) throw new Error("published post requires an author");
+  if (post.topicIds.length === 0) throw new Error("published post requires a topic");
+  if (post.publishedAt && Number.isNaN(Date.parse(post.publishedAt))) throw new Error("publishedAt must be ISO-8601");
+}

package/bundled-templates/astro-blog/examples/route-manifest.ts

@@ -0,0 +1,21 @@
+export const publicRoutes = {
+  blogIndex: "/blog",
+  post: "/blog/[...slug]",
+  topics: "/topics",
+  topic: "/topics/[topic-slug]",
+  author: "/authors/[author-slug]",
+  sitemap: "/sitemap.xml",
+  robots: "/robots.txt",
+} as const;
+
+export const opsRoutes = {
+  dashboard: "/ops",
+  posts: "/ops/posts",
+  postEditor: "/ops/posts/[id]/edit",
+  preview: "/ops/posts/[id]/preview",
+  topics: "/ops/topics",
+  sitemap: "/ops/sitemap",
+  reports: "/ops/reports",
+  siteSettings: "/ops/settings/site",
+  integrations: "/ops/settings/integrations",
+} as const;

package/bundled-templates/astro-blog/starter/.env.example

@@ -0,0 +1,36 @@
+PUBLIC_SITE_URL=https://example.com
+PUBLIC_SITE_NAME=Example Site
+PUBLIC_SITE_LOCALE=en-GB
+PUBLIC_SITE_TIMEZONE=Europe/London
+PUBLIC_POSTS_PER_PAGE=9
+PUBLIC_GRID_COLUMNS=3
+AI_CMO_API_KEY=
+AI_CMO_BASE_URL=https://api.cmo.so
+GA4_MEASUREMENT_ID=
+GSC_VERIFICATION_TOKEN=
+GSC_SITE_URL=https://example.com
+GSC_ACCESS_TOKEN=
+GA4_PROPERTY_ID=
+GA4_ACCESS_TOKEN=
+WORDPRESS_API_TOKEN=
+WORDPRESS_USERNAME=
+WORDPRESS_APP_PASSWORD=
+OPS_AUTH_PROVIDER=
+OPS_LOCAL_TOKEN=
+OPS_LOCAL_ROLE=agency-owner
+MAGGIE_DEPLOY_PROVIDER=node
+CLOUDFLARE_ENV=staging
+BLOG_DATA_SOURCE=sqlite
+BLOG_DB_PATH=.data/maggie.sqlite
+REPORT_EMAIL_WEBHOOK_URL=
+EMAIL_PROVIDER=resend
+RESEND_API_KEY=
+EMAIL_FROM=
+EMAIL_REPLY_TO=
+EMAIL_WEBHOOK_URL=
+MEDIA_STORAGE_PROVIDER=cloudinary
+CLOUDINARY_CLOUD_NAME=
+CLOUDINARY_API_KEY=
+CLOUDINARY_API_SECRET=
+CLOUDINARY_UPLOAD_FOLDER=maggie
+MEDIA_OUTPUT_DIR=public/media/optimized