@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/apps/client-cms-editor/reference/harvest/plans/CMS-EDITOR-HARVEST.md

@@ -0,0 +1,166 @@
+# CMS Editor Harvest Plan
+
+## Working assumption
+
+The current editor is a substantial interactive prototype, not a trusted persistence/publication implementation.
+
+The harvest should preserve interaction design and data-shape clues while replacing fake authority with real CMS contracts later.
+
+## Keep as product requirements
+
+### Navigation and authoring surfaces
+
+- Pages
+- Sections
+- Components
+- Templates
+- Media
+- CRM
+- Settings
+
+These are useful product surfaces even where the current data is mocked.
+
+### Canvas behavior
+
+Keep:
+
+- selected section highlighting
+- parent/iframe message bridge concept
+- section click -> editor selection
+- editor selection -> preview highlight
+- scroll-to-section
+- phone/tablet/desktop preview
+- multi-device responsive preview
+- zoom controls
+
+Reimplement the preview transport against the real CMS draft runtime later.
+
+### Inspector behavior
+
+Keep:
+
+- structured field editing
+- booleans
+- arrays/lists
+- colors
+- media references
+- opacity/ranges
+- JSON fields
+- URLs
+- dates
+- rich text
+- numeric inputs
+- raw structured-field inspection
+- spacing/layout controls
+- theme variables
+- page metadata / SEO
+
+The important idea is schema-driven editing. The current hardcoded rendering is donor material, not the final schema engine.
+
+### Editing workflow
+
+Keep:
+
+- dirty state
+- undo/redo
+- keyboard shortcuts
+- command palette
+- create-page wizard
+- add-section modal
+- template preview/apply flow
+- upload queue UX
+- history restore UX
+- publish/schedule UX
+
+## Adapt, do not copy as authority
+
+### Site/Page/Section types
+
+Current types are useful starting clues:
+
+`Site -> PageData -> Section -> fields/css`
+
+Target should become closer to:
+
+`Site -> Page -> Section -> Block -> Fields -> DraftRevision -> PublicationRevision`
+
+The target CMS should support stable IDs, versioned schemas, provenance, and immutable publication receipts.
+
+### Theme state
+
+Current CSS-variable theme editing is worth preserving.
+
+Target should bind theme variables to a reusable theme contract and BrandPack rather than keeping a free-floating React state object.
+
+### Media
+
+The current media library is simulated.
+
+Target should use AgentSam Asset Core / Content contracts and a provider adapter. UI concepts are reusable; data authority is not.
+
+### CRM / analytics
+
+Treat current CRM contacts, activity, conversion stats, and collaboration indicators as visual references only.
+
+They must never become seeded customer data or production defaults.
+
+## Drop from production extraction
+
+Do not promote:
+
+- fake contacts
+- fake emails
+- fake analytics
+- fake collaboration users
+- fake save delays
+- fake upload progress
+- fake publish success
+- hardcoded "Connected" states
+- hardcoded page metrics presented as real
+- localStorage as CMS authority
+- demo customer/site names as generic defaults
+- deployment assumptions from this repo
+
+## Minimum real CMS proof before calling the replacement functional
+
+1. create/open site
+2. open page
+3. select section/block
+4. edit one field
+5. save to real persistence
+6. reload the browser and observe the saved value
+7. preview draft
+8. confirm public site remains unchanged
+9. publish explicit revision
+10. confirm public runtime resolves the new immutable revision
+
+Only after that loop is proven should AgentSam-assisted editing be considered production integration.
+
+## AgentSam integration target
+
+AgentSam receives explicit CMS context:
+
+- account
+- site
+- route
+- page
+- section
+- block
+- current draft revision
+- current theme
+- permitted CMS actions
+
+AgentSam acts through CMS commands, not direct DOM manipulation.
+
+Examples:
+
+- `cms_get_page`
+- `cms_update_field`
+- `cms_add_section`
+- `cms_move_section`
+- `cms_apply_theme`
+- `cms_create_draft`
+- `cms_preview`
+- `cms_publish`
+
+The model provider remains independent from the CMS implementation.

package/apps/client-cms-editor/reference/harvest/plans/HARVEST-INDEX.md

@@ -0,0 +1,196 @@
+# Studio CMS Editor Harvest Index
+
+## Purpose
+
+This branch turns `studio-cms-editor` into a donor source, not a new runtime authority.
+
+The goal is to preserve everything valuable enough to repurpose while making it difficult to accidentally drag demo state, fake persistence, production-specific deployment glue, or generated artifacts into AgentSam SDK.
+
+Current source truth included by this harvest branch:
+
+- repository: `SamPrimeaux/studio-cms-editor`
+- latest merged source baseline: `origin/main@f0547d7`
+- CMS editor: `app/studio/page.tsx`
+- shared editor styling: `app/globals.css`
+- public storefront implementation: `app/components/Storefront.tsx`
+- public storefront data: `app/storefront-data.ts`
+- public storefront styling: `app/storefront.css`
+- public routes: home, shop, collections, product, journal, story
+- ChatGPT-hosted identity reference: `app/chatgpt-auth.ts`
+- content implementation plan: `plans/INNERANIMALS-CONTENT-001.md`
+- database schema remains intentionally empty
+
+The source is valuable primarily as:
+
+1. a polished CMS/editor interaction donor,
+2. a real public storefront/theme/layout donor,
+3. a ChatGPT identity integration reference,
+4. a historical system example for future AgentSam galleries.
+
+It is **not** assumed to be a functioning production CMS.
+
+## Non-negotiable rule
+
+Installing, auditing, previewing, exporting, or staging this donor must never:
+
+- deploy a Worker,
+- run Wrangler deploy,
+- sync a website,
+- publish a CMS revision,
+- upload assets,
+- write to D1/R2/KV,
+- alter AgentSam SDK runtime packages,
+- alter a customer site,
+- invoke remote mutations.
+
+Those actions belong to later explicit commands in the target system.
+
+## Harvest lanes
+
+### A. CMS editor UX donor
+
+Primary source:
+
+- `app/studio/page.tsx`
+- `app/globals.css`
+
+Keep or adapt the interaction ideas:
+
+- page tree
+- section tree
+- section reorder
+- visibility controls
+- component browser
+- template browser
+- media browser UX
+- content inspector
+- style inspector
+- page/SEO inspector
+- theme/token inspector
+- click-preview-to-select
+- responsive device previews
+- command palette
+- undo/redo
+- HTML import concept
+- URL import concept
+- page history UX
+- publish/schedule UX as UI only
+
+Do not preserve simulated persistence as architecture.
+
+### B. Inner Animals storefront/theme donor
+
+Primary source:
+
+- `app/page.tsx`
+- `app/components/Storefront.tsx`
+- `app/storefront-data.ts`
+- `app/storefront.css`
+- `app/layout.tsx`
+- public storefront route files
+
+Treat this as candidate source for a future package such as:
+
+`@inneranimalmedia/theme-inneranimals-site`
+
+The harvest export preserves the route/layout/component/data source verbatim. Normalizing it into true section/block contracts happens inside the real CMS/theme implementation, not destructively in this donor repo.
+
+See `plans/STOREFRONT-SURFACE-MAP.md`.
+
+### C. ChatGPT identity donor
+
+Primary source:
+
+- `app/chatgpt-auth.ts`
+
+Preserve the hosted ChatGPT identity pattern as a reference adapter for:
+
+`@inneranimalmedia/agentsam-identity`
+
+Target architecture:
+
+`OpenAI/ChatGPT hosted identity -> NormalizedExternalIdentity -> AgentSam account linkage`
+
+Do not leak `oai-authenticated-*` headers into generic CMS contracts.
+
+### D. Content-plan/reference donor
+
+Primary source:
+
+- `plans/INNERANIMALS-CONTENT-001.md`
+
+Keep as implementation intent/provenance. It should not override the reusable CMS/theme contracts.
+
+### E. Runtime/deployment reference
+
+Reference-only:
+
+- `.openai/hosting.json`
+- `vite.config.ts`
+- `next.config.ts`
+- `worker/index.ts`
+- `worker/vpc.ts`
+- `wrangler.production.toml`
+- `docs/workers-vpc.md`
+- `package.json`
+
+These files explain how the old build ran. They are not candidates for automatic adoption into AgentSam SDK.
+
+## One-shot workflow
+
+From this repo:
+
+```bash
+python3 scripts/harvest_audit.py
+python3 scripts/harvest_all.py
+```
+
+That creates a sibling export by default:
+
+`../studio-cms-editor-harvest-export/`
+
+To stage the curated export inside AgentSam SDK without touching active packages:
+
+```bash
+python3 scripts/harvest_all.py \
+  --sdk /Users/samprimeaux/agentsam-sdk \
+  --stage-sdk
+```
+
+The SDK target is:
+
+`apps/_incoming/studio-cms-editor-harvest/`
+
+That directory is intentionally a quarantine/review surface.
+
+## Local preview
+
+```bash
+python3 scripts/preview_local.py
+```
+
+Default browser target:
+
+`http://127.0.0.1:<port>/studio`
+
+Storefront remains available at:
+
+`http://127.0.0.1:<port>/`
+
+Use `--route /` if the storefront should open first.
+
+This launcher never deploys.
+
+## Promotion rule
+
+Nothing in `apps/_incoming/studio-cms-editor-harvest` becomes runtime authority merely because it was staged.
+
+Promotion requires a separate implementation decision and should normally result in one or more of:
+
+- `apps/client-cms-editor` improvements
+- a future `packages/agentsam-cms` family
+- `packages/theme-inneranimals-site`
+- `packages/identity/src/providers/openai`
+- reusable editor primitives/components
+
+The donor remains useful even after promotion because it provides provenance and a historical live example.

package/apps/client-cms-editor/reference/harvest/plans/INNERANIMALS-CONTENT-001.md

@@ -0,0 +1,137 @@
+# INNERANIMALS-CONTENT-001 — Replace storefront concepts with owned content and commerce data
+
+## Status
+
+- Priority: P1
+- Project: `studio-cms-editor`
+- Subsystem: `inneranimals-content`
+- Owner: Agent Sam with Sam Primeaux as content approver
+- State: backlog
+- Production surface: `https://inneranimals.com`
+- Editor surface: `https://inneranimals.com/studio`
+
+## Objective
+
+Turn the approved Inner Animals public-site scaffold into a production storefront using Sam's real brand content, products, photography, inventory, editorial work, and checkout. Preserve the current visual system, route structure, responsive behavior, and the original CMS editor at `/studio`.
+
+This is a content and data-plumbing pass, not a redesign.
+
+## Source-of-truth rules
+
+- Routine copy, images, product details, collections, articles, and campaign settings must be editable through the CMS/data layer rather than hardcoded React arrays.
+- Use owned or explicitly licensed assets stored in the project's Cloudflare media system. Remove demo photography before launch.
+- Existing Shopify/catalog data may be imported when Sam identifies it as authoritative.
+- Never invent prices, inventory, fabric composition, GSM, performance claims, testimonials, athlete quotes, release dates, or shipping promises.
+- Draft missing copy in the established voice, but mark factual gaps for approval.
+- Preserve `/studio` and do not move the editor into IAM dashboard routes under this ticket.
+
+## Workstreams
+
+### 1. Brand foundation
+
+- Confirm display name, wordmark/logo variants, favicon, social preview image, campaign lockup, and announcement-bar copy.
+- Replace placeholder metadata and social sharing content on every public route.
+- Finalize the hero statement, manifesto excerpt, CTA labels, and voice rules.
+
+### 2. Asset migration
+
+- Inventory usable product, campaign, founder, community, and editorial media.
+- Upload approved originals to Cloudflare storage and record stable asset IDs/URLs.
+- Create responsive crops and useful alt text; preserve original files.
+- Replace every demo/Unsplash asset on production.
+
+### 3. Product catalog
+
+For every live product, map and verify:
+
+- name, slug/handle, collection, price, compare-at price if applicable
+- status, inventory policy, sizes, colorways, variants, and SKU
+- product description, fit, intended use, material, care, and GSM when known
+- studio imagery, campaign imagery, alt text, and display order
+- size guide, model measurements, shipping/returns note, and related products
+
+Do not publish a field that has not been verified from Sam's source data.
+
+### 4. Homepage population
+
+Populate the existing modules without changing their approved layout:
+
+- cinematic campaign/drop hero
+- Shop by Instinct: Train, Recover, Roam, Everyday
+- Issue 001 featured products
+- manifesto break
+- Wolf, Bear, Panther, and Bull archetypes, unless Sam renames them
+- field film or training story
+- Field Journal highlights
+- The Pack community gallery
+- Join the Pack membership/email capture
+
+### 5. Collections and product pages
+
+- Populate `/shop` and each approved collection with real catalog data and filters.
+- Populate product routes with verified variants, sizing, fit, media, specifications, availability, and related editorial content.
+- Keep sticky mobile purchase controls and ensure unavailable variants cannot be purchased.
+
+### 6. Story and journal
+
+- Replace concept copy in `/story` with the approved founder story, manifesto, and brand code.
+- Publish the first approved journal articles with author, date, excerpt, hero media, body, SEO fields, and related products.
+- Do not fabricate community or athlete stories.
+
+### 7. Commerce and lifecycle wiring
+
+- Connect the authoritative catalog, cart, inventory, and checkout provider selected by Sam.
+- Connect Join the Pack to the approved email/CRM destination with consent language and a confirmed success state.
+- Record orders and leads in the appropriate system without exposing secrets in the browser.
+- Add analytics events for product view, collection view, add to cart, checkout start, purchase, article view, and signup.
+
+### 8. CMS editing contract
+
+- Model homepage modules, navigation, collections, products, journal entries, story content, SEO, and campaign settings in the CMS/data layer.
+- Map those records to the public routes with loading, empty, and error states.
+- Ensure changes can be previewed and published from `/studio` without editing source files.
+- Preserve drafts and prevent unpublished content from leaking into public responses.
+
+### 9. Accessibility, SEO, and legal checks
+
+- Meaningful alt text, keyboard access, visible focus, reduced motion, and WCAG AA text contrast.
+- Unique titles/descriptions, canonical URLs, Open Graph data, product structured data, article structured data, sitemap, and robots behavior.
+- Link approved privacy, terms, returns, shipping, and contact policies before enabling checkout.
+
+## Inputs required from Sam
+
+1. Identify the authoritative product/inventory source and the products included in Issue 001.
+2. Provide or approve logo files and the first campaign/product image set.
+3. Approve the hero headline, manifesto, and founder-story source.
+4. Confirm whether Wolf, Bear, Panther, and Bull remain the collection archetypes.
+5. Choose the checkout provider and newsletter/CRM destination.
+6. Provide or approve shipping, returns, privacy, and terms content.
+
+Agent Sam may infer formatting, navigation labels, copy polish, alt-text drafts, responsive crops, and product ordering. It must pause for approval when a missing answer would create a factual claim or irreversible commerce setting.
+
+## Acceptance criteria
+
+- No placeholder, concept, or unlicensed imagery is visible on production.
+- Every public route is populated, linked, responsive, and scrollable.
+- Product facts, prices, variants, and inventory match the authoritative source.
+- Cart and checkout work end-to-end, or non-purchasable products use an explicitly approved waitlist state.
+- Routine content changes are possible through the CMS without a code deploy.
+- `/studio` remains functional and visually unchanged.
+- Mobile QA includes navigation, filtering, product selection, sticky purchase controls, forms, and checkout on a 375px viewport.
+- Keyboard, reduced-motion, image-alt, contrast, SEO, sitemap, and structured-data checks pass.
+- Production verification covers `/`, `/shop`, every collection, at least one product, `/journal`, one article, `/story`, and `/studio`.
+
+## Evidence and handoff
+
+Attach to the ticket before shipping:
+
+- source PR and deployed commit
+- imported catalog record count and rejected/error count
+- Cloudflare asset identifiers for the approved media set
+- CMS record identifiers or export snapshot
+- live-route verification results and checkout receipt/test order
+- list of any intentionally deferred fields or assets
+
+## Suggested Agent Sam kickoff
+
+Read this plan, inspect the current public routes and CMS schema, then produce a content inventory that separates: ready to import, needs Sam approval, and missing. Do not redesign the scaffold. Begin implementation only with verified source material, keep the site deployable after each workstream, and report blockers as specific content decisions rather than substituting invented facts.

package/apps/client-cms-editor/reference/harvest/plans/NO-IMPLICIT-SIDE-EFFECTS.md

@@ -0,0 +1,87 @@
+# No Implicit Side Effects
+
+This is a hard product rule for all harvest and future AgentSam integration work.
+
+## Capability availability is not action authorization
+
+Installing AgentSam SDK or a theme/CMS/identity package means:
+
+> the capability is available
+
+It never means:
+
+> execute the capability against a customer system
+
+## Safe/read-only classes
+
+These should be non-mutating by default:
+
+- inspect
+- inventory
+- scan
+- audit
+- preview
+- analyze
+- plan
+- diff
+- validate
+
+## Local/staging mutation classes
+
+These may write only to an explicit local/staging target:
+
+- scaffold
+- export
+- stage
+- generate
+- apply-local
+
+They must not contact production resources unless a separate explicit option says so.
+
+## Remote/customer mutation classes
+
+These require explicit invocation and explicit target:
+
+- sync
+- upload
+- promote
+- publish
+- deploy
+- migrate
+- rotate
+- delete
+
+A generic SDK lifecycle hook must never invoke them.
+
+## Harvest scripts on this branch
+
+The Python scripts added by this branch:
+
+- never call Wrangler
+- never deploy
+- never publish
+- never access D1/R2/KV
+- never run npm lifecycle commands
+- never change Git branches
+- never push commits
+- never write into active AgentSam SDK packages
+
+The only optional SDK write target is:
+
+`apps/_incoming/studio-cms-editor-harvest/`
+
+and it requires the explicit `--stage-sdk` flag.
+
+## Promotion receipts
+
+Future mutating commands should emit a receipt containing at minimum:
+
+- action
+- target
+- source revision
+- files/resources affected
+- timestamp
+- result
+- rollback/recovery information when available
+
+This is especially important for theme/content/CMS systems because package discovery and preview must remain safe.