@easysociable/cli 0.1.3 → 0.1.4

package/content-engine/starter/engine.json

@@ -6,6 +6,9 @@
     "runs": "runs",
     "exports": "exports",
     "topics": "topics",
+    "needs": "needs",
+    "products": "products",
+    "recommendations": "recommendations",
     "swipe": "swipe",
     "profiles": "profiles",
     "inbox": "inbox",

package/content-engine/starter/needs/README.md

@@ -0,0 +1,38 @@
+# needs/
+
+First-class **user-needs library**. Not an inbox type. Inbox stays structure / link / insight.
+
+| Path | Role |
+|------|------|
+| `_index.md` | Quote registry (source of truth for list/status) |
+| `entries/N-YYYYMMDD-XX.md` | One need: verbatim quote + sightings + optional gloss |
+| `_template.md` | Entry shape |
+
+## Status machine (only these words)
+
+```text
+captured  → just written, or still captured after a synonym merge (frequency ≥ 1)
+promoted  → and only when a T- exists whose need_ids contain this N-; topic_ids lists that T-
+retired   → user discarded
+```
+
+Do **not** use `clustered`. Merge is not a status.
+
+## Do not
+
+- Invent quotes or FAQ template sentences
+- Treat a watchlist hook / viral title as a need
+- Put `N-` into a topic `capture_id` (`capture_id` is inbox `C-…` only)
+- Hosted clustering
+
+## Quote shape (not product copy, not index rows)
+
+These lines are the **shape** of a creator's audience talking. They are **not** EasySociable features and must **not** be seeded as rows:
+
+- 我不知道自己适合做什么 AI 自媒体方向
+- 我每天用 AI 写稿，还是断更
+- 我账号有流量，但为什么没人咨询
+- 我想接广告，要多少粉丝才可以
+- 我不会出镜，能不能先做图文
+
+When a quote is reused as published copy, redact names / DMs / student details.

package/content-engine/starter/needs/_index.md

@@ -0,0 +1,31 @@
+# Needs index
+
+Registry of **audience quotes**. Source of truth for need lifecycle.
+
+Newest rows on top. **Zero starter rows** — do not invent quotes.
+
+| id | date | profile | source_type | quote | speaker | frequency | status | topic_ids | file |
+|----|------|---------|-------------|-------|---------|-----------|--------|-----------|------|
+
+## Columns
+
+| Column | Meaning |
+|--------|---------|
+| `id` | `N-YYYYMMDD-XX`, increment per day (same shape as `C-` / `D-` / `T-`) |
+| `date` | First sighting date |
+| `profile` | Default current `profile_id` |
+| `source_type` | `comment` \| `dm` \| `consult` \| `faq` \| `student` \| `other` |
+| `quote` | **Verbatim.** Never put a gloss in this cell |
+| `speaker` | Optional; anonymous → `anon`. Do not invent names |
+| `frequency` | Integer, default 1. Same-meaning merge: `+1` on this row, append a sighting — do **not** create a second row |
+| `status` | `captured` \| `promoted` \| `retired` (**never** `clustered`) |
+| `topic_ids` | Cited `T-…`, comma-separated. Non-empty **iff** status=`promoted` |
+| `file` | `needs/entries/N-….md` |
+
+## Agent rules
+
+- Every need: new row + new `entries/<id>.md`
+- Merge is not a new status. After a user-approved synonym merge, keep `captured`, bump `frequency`, append sighting
+- Do not mark `promoted` without a `T-` whose `need_ids` contain this `N-`
+- Scan-for-topics input set: `status=captured` (`topic_ids` empty). Max 5 `produce`
+- Quotes may include DMs / student info. Keep local. Redact PII if a quote is used in published copy

package/content-engine/starter/needs/_template.md

@@ -0,0 +1,24 @@
+---
+id: N-YYYYMMDD-XX
+date: YYYY-MM-DD
+profile: default
+source_type: comment | dm | consult | faq | student | other
+frequency: 1
+status: captured
+---
+
+# N-… — five-character-or-less need label (Agent-coined, not the quote)
+
+## Quote
+> （verbatim, unedited）
+
+## Sightings
+| date | source_type | where |
+|------|-------------|-------|
+| YYYY-MM-DD | comment | url or `pasted` |
+
+## Our gloss（optional, separate from the quote）
+One line: what they are hiring us to solve.
+
+## Status
+captured

package/content-engine/starter/needs/entries/README.md

@@ -0,0 +1,5 @@
+# needs/entries/
+
+One file per need (`N-YYYYMMDD-XX.md`). Registry: `../_index.md`.
+
+Do not pre-seed FAQ rows.

package/content-engine/starter/products/README.md

@@ -0,0 +1,38 @@
+# products/
+
+First-class **product facts library**. Products describe what the creator
+offers; they are not audience needs, topics, or published claims.
+
+| Path | Role |
+|------|------|
+| `_index.md` | Product registry and lifecycle |
+| `entries/P-*.md` | Product facts, boundaries, pricing, proof and claims |
+| `_template.md` | Product entry shape |
+
+## Relationship to the content engine
+
+```text
+Needs (demand evidence) + Profile (identity)
+  → Topic (editorial judgment)
+  → optional Product fit (offer context)
+  → Run
+```
+
+- A `Need` records what an audience member actually said.
+- A `Product` records what is currently offered and what it does not promise.
+- A `Topic` decides whether something is worth saying. It may cite zero, one, or
+  several products.
+- Product fit never makes a Topic `ready` by itself, and a product description
+  never becomes a Need quote.
+
+## Rules
+
+- Keep product facts current. Prices and entitlements must include an
+  `effective_from` date and a source of truth.
+- Do not invent customers, outcomes, metrics, testimonials or proof.
+- Mark a product `retired` instead of silently deleting a product used by a
+  Topic or Run.
+- Use `product_fit: none` for useful education that does not need a product
+  connection. Do not force a CTA into every Topic.
+- Product claims here describe the offer. The `wiki/claims/` catalog tracks
+  propositions tested through published content; they are different objects.

package/content-engine/starter/products/_index.md

@@ -0,0 +1,24 @@
+# Products index
+
+Newest rows on top. This is the registry; product facts live in the entry
+file.
+
+| id | name | status | audience | price | effective_from | file |
+|----|------|--------|----------|-------|----------------|------|
+| P-001 | EasySociable | active | creators and teams producing branded multi-page social visuals | see entry | 2026-09-04 | products/entries/P-001-easysociable.md |
+
+## Status values
+
+| status | Meaning |
+|--------|---------|
+| `draft` | Being defined; do not use for product claims |
+| `active` | Current offer; may be cited by Topics and Runs |
+| `retired` | No longer offered; retained for historical references |
+
+## Agent rules
+
+- Read the product entry before making a product claim.
+- `price` is a lookup hint only; use the dated entry for exact pricing and
+  entitlements.
+- A Topic may cite `product_ids: none` even when the account has active
+  products.

package/content-engine/starter/products/_template.md

@@ -0,0 +1,56 @@
+---
+id: P-YYYYMMDD-XX
+name:
+status: draft
+effective_from: YYYY-MM-DD
+source_of_truth:
+---
+
+# Product name
+
+## Product promise
+
+One sentence describing the customer change. Do not promise an outcome the
+product cannot control.
+
+## What it is
+
+## Best for
+
+## Not for
+
+## Problem
+
+## Mechanism
+
+How the product addresses the problem.
+
+## Not solving
+
+Explicit exclusions and limitations.
+
+## Pricing and entitlements
+
+Include currency, billing period, limits and plan differences. Record the
+effective date above.
+
+## Proof
+
+Named evidence only. Empty is valid.
+
+## Objections
+
+## Claims
+
+### Safe to say
+
+### Say carefully
+
+### Do not say
+
+## CTA
+
+When to educate, mention, invite, or sell.
+
+## Version notes
+

package/content-engine/starter/products/entries/P-001-easysociable.md

@@ -0,0 +1,150 @@
+---
+id: P-001
+name: EasySociable
+status: active
+effective_from: 2026-09-04
+source_of_truth:
+  - docs/prd.md
+  - docs/pricing-v1.md
+  - apps/easysociable/app/routes/home.tsx
+---
+
+# EasySociable
+
+## Product promise
+
+Turn an agent-produced content argument into a reusable, branded,
+reviewable, multi-page social visual pack.
+
+## What it is
+
+EasySociable is the hosted visual production layer for an external Agent. It
+provides reusable Page Templates, Brands, durable Slideshow Runs, Studio
+review/editing, and browser Download of the reviewed PNG pack.
+
+The Agent supplies the content reasoning and page structure. EasySociable does
+not write the content or provide a hosted LLM.
+
+## Best for
+
+- Creators who already use Codex, Claude Code, or a comparable Agent for
+  content reasoning.
+- Creators and teams producing branded carousels across TikTok, Instagram,
+  LinkedIn, or Threads.
+- Operators who need reusable visual systems, role-specific layouts, and a
+  review step before download.
+
+## Not for
+
+- Users looking for a browser-only content writing assistant.
+- Users who want a general-purpose freeform design editor instead of a
+  constrained reusable visual system.
+- Users who want EasySociable to manage their social accounts or publish
+  automatically.
+
+## Problem
+
+An Agent can produce the argument, but the visual production context is often
+lost: each carousel starts from a blank design, brand instructions are
+repeated, and a small revision can require regeneration.
+
+When one idea must become several platform deliverables, the operator also has
+to repeat layout and export work while checking platform-specific canvases.
+
+## Mechanism
+
+- Page Templates are discoverable by layout role such as `cover`, `hook`,
+  `value`, `steps`, `proof`, and `cta`, so a content structure can be matched
+  to an appropriate visual layout.
+- A Brand and reusable templates persist visual decisions across future Runs.
+- Studio keeps the complete Run reviewable and allows supported text and image
+  slot edits before Download.
+- Platform-specific Layout Family variants and exports adapt the same
+  structured content to supported canvas presets.
+
+## Not solving
+
+- Content strategy, audience research, or the quality of the Agent's thesis.
+- Guaranteed reach, engagement, conversions, or viral performance.
+- Automatic social posting or social-account connection.
+- A hosted LLM or a replacement for the user's Agent.
+- Unlimited arbitrary canvas editing or unrestricted template composition.
+
+## Pricing and entitlements
+
+Early-access prices; list prices and free limits may change.
+
+| Plan | Monthly | Annual | Slideshow Download | Brands | Image library |
+|------|---------|--------|--------------------|--------|---------------|
+| Free | $0 | — | 3/month, 1 platform per pack | 1 | 2 GB |
+| Creator | $19 | $190/year | Unlimited, all selected V1 platforms | 5 | 50 GB |
+| Pro | $39 | $390/year | Unlimited, all selected V1 platforms | 25 | 200 GB |
+| Agency | Sales-led | Contract | Contract | >25 | >200 GB |
+
+Paid plans include the full system-template catalog, up to 20 pages per
+Slideshow Run, private drafts, three API keys, no overage and no watermark.
+Pixels leave the product through Studio Download; CLI/MCP is not a final PNG
+factory.
+
+## Proof
+
+No customer proof is recorded here. Do not invent testimonials, adoption
+metrics or performance improvements.
+
+## Objections
+
+### “Canva already does this.”
+
+Canva is the broader freeform design workspace. EasySociable is for an
+Agent-first, repeatable visual production workflow with role-aware templates,
+durable Runs and Studio review.
+
+### “Can the Agent write my post?”
+
+The Agent can do that outside EasySociable. EasySociable owns the visual
+production layer.
+
+### “Can I publish directly?”
+
+V1 produces a reviewed Download from Studio. It does not connect social
+accounts or publish posts.
+
+## Claims
+
+### Safe to say
+
+- Reuse saved Brands and Page Templates.
+- Select layouts by supported page role.
+- Review and edit supported slots in Studio before Download.
+- Create platform-specific variants for supported V1 platforms and canvases.
+
+### Say carefully
+
+- “One idea, multiple platforms” means the structured Run is adapted and
+  exported for supported platform formats; it does not mean one identical file
+  is valid everywhere.
+- “Faster” requires a user-specific baseline. Do not claim a universal time
+  saving.
+- “Branded” means the configured Brand and selected templates are applied; it
+  does not mean every creative decision is automatically correct.
+
+### Do not say
+
+- “Guaranteed higher engagement.”
+- “One-click automatic publishing.”
+- “AI writes all your content.”
+- “No review is needed.”
+- “Every platform receives the same file.”
+
+## CTA
+
+- `educate`: explain the Agent-to-visual production gap.
+- `mention`: show how a role-specific template or Brand persists.
+- `invite`: ask users to try a real content Run and review it in Studio.
+- `sell`: use only when the audience has a validated need for repeated
+  branded visual production.
+
+## Version notes
+
+- 2026-09-04: early-access pricing and V1 entitlements from
+  `docs/pricing-v1.md`.

package/content-engine/starter/profiles/_index.md

@@ -3,11 +3,14 @@
 Reusable **content profiles**: pillars + audience + voice.  
 Accounts point here; do not copy profile bodies into account files.
 
-| id | path | voice | one_liner | accounts |
-|----|------|-------|-----------|----------|
-| default | profiles/default/ | `profiles/default/voice.md` | Replace this one-liner with the profile’s job | your-handle |
+| id | path | voice | one_liner | accounts | product_ids | recommendation_scope |
+|----|------|-------|-----------|----------|-------------|---------------------|
+| default | profiles/default/ | `profiles/default/voice.md` | Replace this one-liner with the profile’s job | your-handle | none | none |
 
 ## Voice column
 
 - Empty or `profile` → load `profiles/<id>/voice.md`
 - Explicit path → load that file instead
+
+`profiles/<id>/lanes.md` describes publishing lanes such as teaching, building,
+reviewing and comparing. A lane is not a replacement for a pillar.

package/content-engine/starter/profiles/default/README.md

@@ -6,6 +6,9 @@ Replace this starter profile before the first serious draft.
 |------|------|
 | `pillars.md` | Topics this profile may cover |
 | `audience.md` | Readers + per-platform emphasis |
-| `voice.md` | Identity + tone |
+| `voice.md` | Identity + Experience + Values + Persona |
+| `stories.md` | Story inventory (cite or none) |
+| `boundaries.md` | Creator must-avoid (Not covering / Never claim) |
+| `expression.md` | Expression likes / dislikes |
 
 Accounts: see `accounts/_index.md`.

package/content-engine/starter/profiles/default/boundaries.md

@@ -0,0 +1,14 @@
+# Boundaries — profile `default`
+
+**Role:** Topics, audiences, and claims this creator will not write.  
+**Not:** Audience “Not for” (`./audience.md`) — that excludes readers.
+
+Missing this file is a **hard-gate fail**. Write this starter, then interview. Never invent boundaries.
+
+## Not covering
+
+- (fill)
+
+## Never claim
+
+- (fill)

package/content-engine/starter/profiles/default/expression.md

@@ -0,0 +1,18 @@
+# Expression — profile `default`
+
+**Role:** Concrete likes and dislikes (phrases, structures, clichés).  
+**Not:** Hype bans (`./voice.md` Do not say).
+
+Missing this file = `profile: partial`, not a hard-gate fail.
+
+## Likes
+
+1. (fill)
+2. (fill)
+3. (fill)
+
+## Dislikes
+
+1. (fill)
+2. (fill)
+3. (fill)

package/content-engine/starter/profiles/default/lanes.md

@@ -0,0 +1,12 @@
+# Content lanes
+
+Lanes describe how this profile publishes, not what the profile is about.
+Pillars remain the durable subjects.
+
+| id | name | purpose | status |
+|----|------|---------|--------|
+| teach | Teaching | Explain systems, mechanisms and workflows | active |
+| build | Building in public | Share implementation decisions and lessons | active |
+| review | Tool review | Review third-party AI products with evidence | active |
+| compare | Tool comparison | Compare options by a stated user job | active |
+| offer | Product education | Explain owned product mechanisms and limits | active |

package/content-engine/starter/profiles/default/stories.md

@@ -0,0 +1,15 @@
+# Stories — profile `default`
+
+**Role:** Narrative inventory the draft may cite.  
+**Not:** Identity table facts (`./voice.md` Experience).
+
+0–1 stories is enough for a first session (`profile: partial`). Skip if the user has none they will make public.
+
+## Stories
+
+### S1 — (title)
+
+- **Situation:** (fill)
+- **Choice:** (fill)
+- **Lesson:** (fill)
+- **Public:** yes | no

package/content-engine/starter/profiles/default/voice.md

@@ -13,12 +13,26 @@
 | **Point of view** | (fill) |
 | **Not claiming** | Invented metrics, customers, quotes, or team size |
 
+## Experience
+
+Facts copy may cite (year, role, thing done). Write `not claiming` when unknown.
+
+- (fill)
+
+## Values
+
+Claims this profile will always make / will never make. Repeatable topics go in `pillars.md`, not here.
+
+- (fill)
+
 ## Persona
 
+- (fill)
 - Direct. Concrete nouns. Address the reader as **you**.
 - Do not invent bio facts not listed in Identity.
 
 ## Do not say
 
+- (fill)
 - Fake social proof
 - Empty hype (“game-changer”, “unlock your potential”)

package/content-engine/starter/recommendations/README.md

@@ -0,0 +1,21 @@
+# recommendations/
+
+First-class **third-party product and tool library**. This is separate from
+`products/`: entries here are products the profile may review, compare, or
+recommend, not products EasySociable owns or sells.
+
+```text
+Profile + Needs + review evidence
+  → Topic
+  → optional recommendation_ids
+  → Run
+```
+
+## Rules
+
+- Do not treat a recommendation as an owned Product or as a product CTA.
+- Do not copy vendor marketing claims into `quote` or evidence.
+- Record the research date and source URLs. Prices and features can change.
+- Record affiliate, sponsorship, or other commercial relationships when known.
+- A recommendation needs a review basis: observed workflow, named source,
+  comparison, or user-provided evidence. An empty entry is not a review.

package/content-engine/starter/recommendations/_index.md

@@ -0,0 +1,21 @@
+# Recommendations index
+
+Third-party tools and products available for review or comparison. No starter
+entries are provided.
+
+| id | name | status | category | profiles | pillars | last_researched | relationship | file |
+|----|------|--------|----------|----------|---------|-----------------|--------------|------|
+| -- | ---- | ------ | -------- | -------- | ------- | --------------- | ------------ | ---- |
+
+## Status values
+
+| status | Meaning |
+|--------|---------|
+| `candidate` | Captured for possible research; not publishable |
+| `researched` | Evidence and limits recorded |
+| `active` | Available for Topics and reviews |
+| `retired` | No longer maintained or relevant |
+
+`profiles` is a comma-separated many-to-many association. Use `*` only when
+the subject is intentionally shared across all profiles. `pillars` records
+where the subject is relevant; it does not make the subject an owned product.

package/content-engine/starter/recommendations/_template.md

@@ -0,0 +1,44 @@
+---
+id: R-YYYYMMDD-XX
+name:
+status: candidate
+category:
+profiles: default
+pillars:
+last_researched: YYYY-MM-DD
+relationship: none | affiliate | sponsor | client | other
+source_urls:
+---
+
+# Recommendation subject
+
+## What it is
+
+## Best for
+
+## Not for
+
+## Problem addressed
+
+## Observed workflow
+
+## Strengths
+
+## Limitations
+
+## Alternatives
+
+## Pricing snapshot
+
+Include currency, plan, limits and date. Do not assume the price is current.
+
+## Evidence
+
+Named sources, tests, screenshots, or user reports. Empty is not publishable.
+
+## Disclosure
+
+State affiliate, sponsorship, ownership, or other commercial relationship.
+
+## Review notes
+

package/content-engine/starter/runs/_template/brief.md

@@ -43,7 +43,7 @@ gate_pass: false
 ## Constraints
 
 - **must_include:**
-- **must_avoid:**
+- **must_avoid:** (merge `profiles/<id>/boundaries.md` + voice Do not say)
 
 ## Selection (required; none allowed)
 

package/content-engine/starter/runs/_template/pack.md

@@ -2,6 +2,7 @@
 # PagePack — this run is already one platform (image decks only; not pure x text)
 # Prefer filename: pack.md (or pack-<platform>.md)
 # Create when: user wants carousel/slideshow AND rubric SHIP for this run.
+# Write the Arc line before pages. Do not default Cover → Point → Steps → Recap → CTA.
 ---
 status: unused
 id:
@@ -20,23 +21,30 @@ page_count: 0
 - **claim_id:**
 - **language:** en
 
+## Arc
+
+<!-- One line: the argument that needs page turns. Required before Pages. -->
+<!-- Recipes: cost-mechanism | listicle | mistakes | claim-proof | compare | (named) -->
+
+- **one_liner:**
+- **recipe:**
+
 ## Pages
 
-<!-- Each page: role + slots. Text only — no private AST. -->
+<!-- Each page: role is a layout retrieval tag, not sequence position. -->
+<!-- First page is not automatically cover. Text only — no private AST. -->
 
 ### page 1
 
-- **role:** cover
+- **role:**
 - **slots:**
-  - title:
-  - subtitle:
+  - text_0:
 
 ### page 2
 
-- **role:** body
+- **role:**
 - **slots:**
-  - heading:
-  - body:
+  - text_0:
 
 <!-- …repeat through page_count… -->
 

package/content-engine/starter/runs/_template/packet.md

@@ -23,3 +23,9 @@
 ## Brief essentials
 
 ## Hard bans
+
+## Boundaries (must_avoid — from boundaries.md + voice Do not say)
+
+## Expression likes / dislikes
+
+## Story inventory (cite or none)

package/content-engine/starter/swipe/_template.md

@@ -18,7 +18,9 @@ tags: []
 
 - …
 
-## Beats / pages (structure only — no full copy)
+## Beats / pages (argument structure only — no full copy)
+
+<!-- Not Cover → Point → Steps → Recap → CTA. Those are catalog family names. -->
 
 1. …
 2. …