# ContentForge
🌐 **Read this in:** [English](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.md) · [हिन्दी](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.hi.md) · [中文](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.zh-CN.md) · [日本語](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ja.md) · [한국어](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ko.md) · [Español](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.es.md) · [Português](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.pt-BR.md) · [العربية](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ar.md) · [اردو](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ur.md) · [தமிழ்](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ta.md) · [বাংলা](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.bn.md) · [Русский](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/README.ru.md)
> **You need to ship 30 articles this quarter that sound human, cite real sources, link into your funnel, and survive an editor who checks. Your team is three people. You have nine weeks. Your last "AI-written" batch got flagged for hallucinated stats — and the batch before that quietly went stale and nobody noticed.**
Run `/contentforge:create-content` against each topic. The 10-phase pipeline produces a publication-ready `.docx` with a 43-pattern humanizer, a fact-checker subagent, three-category internal linking, and C2PA provenance for EU AI Act compliance — in 30–60 minutes per piece. Then the part no single-shot tool has: **the lifecycle loop.** Every published piece is measured (`cf-aeo-check`), audited for decay (`cf-audit`), and fed back into the next calendar and the next brief — through durable file contracts, so what the system learns about your brand survives the session that learned it.
Enterprise content production system for TechShu delivery teams — **22 skills · 13 specialist agents · 10 quality gates · 43-pattern AI-detection humanizer · a run auditor that re-derives every gate before a run may call itself finished · 28 Python scripts, stdlib-only**. Built for marketing teams producing high volumes of long-form content that needs brand voice consistency, citation integrity, and an internal-link strategy that turns content into a funnel. Installs on **Claude Code** (CLI + IDE), **Anthropic Cowork**, **OpenAI Codex**, **Cursor 2.5+**, **GitHub Copilot CLI**, **Google Antigravity 2.0**, **Hermes Agent**, **OpenClaw**, and **Grok** (xAI Build CLI) + 35+ Agent Skills platforms — with hero skills uploadable to **claude.ai (web)** as `.skill` release assets.
[](CHANGELOG.md)
[](LICENSE)
[](tests/)
[](#supported-surfaces-v412)
[](#cross-platform-compatibility)
[](docs/c2pa-production-cert.md)
> 🆕 **Just shipped — v4.1.2 (August 17, 2026): schema-clean hooks manifest.** Cowork's plugin validation rejects unknown top-level fields in `hooks.json`, and ours carried a `_readme` rationale field ([digital-marketing-pro#9](https://github.com/teachskillofskills-ai/DigitalMarketingPro-techshu/issues/9) — the same defect shipped in all three suite plugins). The rationale now lives in [hooks/README.md](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/hooks/README.md), `hooks.json` is exactly `{"hooks": {}}`, and a new guard keeps it that way. Translations re-stamped. Previously —
>
> **v4.1.1 (August 17, 2026): the README goes global, and shows its receipts.** This README now reads in **12 languages** (हिन्दी, 中文, 日本語, 한국어, Español, Português, العربية, اردو, தமிழ், বাংলা, Русский — switcher at the top, every translation version-stamped and guard-checked), carries **the real artifacts from a real validated run** — the actual chart the pipeline rendered, the actual humanizer before/after edits, the actual 9.0/A scorecard and CLEAN audit verdict ([see them](#the-artifacts-themselves--real-output-you-can-inspect)) — and documents **running ContentForge on OpenAI surfaces** (Codex CLI/IDE/App and ChatGPT via Agent Plugins 1.0) with the same depth as the Claude surfaces, including [updating on all nine platforms](#updating). Previously —
>
> **v4.1.0 (August 17, 2026): two new surfaces.** ContentForge now installs natively on **Grok (xAI Build CLI)** — `grok plugin install teachskillofskills-ai/ContentForge-techshu` — via a first-class `.grok-plugin/` manifest pair, version-locked to every other manifest by the release-consistency suite. And five **hero skills now ship as claude.ai-uploadable `.skill` release assets** (`cf-brief`, `cf-social-adapt`, `cf-translate`, `cf-video-script`, `cf-aeo-check`), built by a deterministic packager (`scripts/build-skill-assets.py`) that bundles each skill's config/template dependencies and *refuses to package* any skill whose prose references a file that wouldn't exist after upload — so a claude.ai user never downloads a skill with broken references. [Install for your platform →](#supported-surfaces-v412)
>
> **v4.0.0 (August 17, 2026): the lifecycle release.** ContentForge 3.x was a production pipeline; 4.0 makes it a content **system**. Three architectural changes, each grounded in a defect a real run exposed: **(1) The lifecycle loop closed.** `cf-audit` findings now land in a validated, canonical per-brand store (`scripts/audit-ledger.py`) that `cf-calendar` and `content-refresh` read across sessions; AI-visibility history (`aeo/checks.json`) feeds the freshness model; and each run's verified link inventory merges back into `brand_pages` automatically — conversion pages only ever *staged* for your confirmation, because a CTA is a commercial decision the system must not make for you. Before 4.0 every one of those handoffs was conversational, and worked only while one session held both ends. **(2) The pipeline contract is data.** `config/pipeline-graph.json` declares every phase's reads, writes, gates, and budgeted loop edges — drift-guarded both directions against the agent contracts, the checkpoint manager, and the run auditor. Encoding it immediately found six under-declared inputs the prose table had lost. **(3) The pipeline learns, with floors.** New `scripts/telemetry.py` aggregates loop history, phase timings, and the humanizer's per-pattern hit counts across runs — recurring patterns reach the next drafter brief as advisories behind a recurrence floor, and never touch a gate, a threshold, or a verdict. 22 skills · 27 scripts · 498 tests. [Release notes →](#release-notes) · [Full changelog →](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/CHANGELOG.md)
```bash
# Install in Claude Code (CLI or VS Code/JetBrains extension):
/plugin marketplace add teachskillofskills-ai/techshu-marketplace
/plugin install contentforge@techshu
# Install in Cowork: use the Plugins panel in the UI -- /plugin slash
# commands DON'T work in Cowork (or Claude.ai / Claude Desktop).
# Open Plugins panel -> Add marketplace -> paste teachskillofskills-ai/techshu-marketplace
# -> Install ContentForge from the listed plugins.
# Install on Hermes Agent (Nous Research):
hermes plugins install teachskillofskills-ai/ContentForge-techshu
# Install on OpenClaw:
openclaw plugins install git:github.com/teachskillofskills-ai/ContentForge-techshu
# Install on Grok (xAI Build CLI):
grok plugin install teachskillofskills-ai/ContentForge-techshu
```
> If ContentForge saves your team time, [give it a star ⭐](https://github.com/teachskillofskills-ai/ContentForge-techshu/stargazers) — it's the single thing that helps other marketing teams find it.
---
## Why ContentForge
Most AI writing tools produce one draft, in one tone, with no quality gates, and forget the piece the moment it ships. The output reads like AI, factual claims are unverified, internal links don't exist, brand voice drifts, the file format is markdown when the editor wants Word — and six months later nobody knows which pieces went stale. ContentForge fixes this end to end:
| Capability | Why it matters |
|---|---|
| **10-phase pipeline with a quality gate after every phase** | Bad output is caught and re-run before it propagates downstream |
| **43-pattern AI-detection humanizer** + self-critique meta-pass | Output reads human, not AI — measured advisory tell-scan + burstiness metrics (`text-metrics.py --ai-tell-scan`) |
| **Fact-checker subagent** verifies URLs and cross-references claims | Citations work and aren't hallucinated — every statistic traces to a verified ledger entry |
| **Three-category internal linking** (topical / commercial / authority) | Content becomes a funnel, not a stranded page |
| **Real `.docx` output** with embedded SEO + Quality + Production + Internal-Link appendices | Editor / design team gets a working Word file, not markdown |
| **A run auditor that re-derives every gate from the artifacts** | "The pipeline says it finished" and "the artifacts prove it finished" can never drift apart silently — `finalize --status completed` refuses without a fresh CLEAN verdict |
| **The lifecycle loop (v4.0)** — audit → refresh → measure → plan, joined by file contracts | Published content stops being fire-and-forget: decay is detected, refreshes are prioritized from data, and what the pipeline learns about your brand compounds |
| **C2PA content provenance signing** for EU AI Act Article 50 compliance | Long-form AI-assisted content distributed in EU markets needs provenance from 2 Aug 2026 |
---
## Supported surfaces (v4.1.2)
| Platform | Install command | Manifest path | Status |
|---|---|---|---|
| **Claude Code** CLI + IDE extension | `/plugin install contentforge@techshu` | `.claude-plugin/plugin.json` | Full support (canonical for solo devs) |
| **Anthropic Cowork** | Plugins panel in UI → Add marketplace → `teachskillofskills-ai/techshu-marketplace` → Install ContentForge | same `.claude-plugin/` files | **Recommended for teams** — `/contentforge:cf-cowork-setup` wires Google Drive for team-shareable output (and, in 4.0, for the lifecycle stores that make the loop compound across sessions) |
| **OpenAI Codex** CLI + IDE + App | `codex plugin marketplace add teachskillofskills-ai/techshu-marketplace` then `codex plugin install contentforge@techshu` | `.codex-plugin/plugin.json` (published OpenAI schema) | Full skills + MCP support |
| **Cursor 2.5+** | In any Cursor Agent chat: `/add-plugin contentforge@https://github.com/teachskillofskills-ai/ContentForge-techshu` | `.cursor-plugin/plugin.json` (verified Cursor 2.5+ JSON Schema) | Full skills + agents + commands support |
| **GitHub Copilot CLI** | `copilot plugin marketplace add teachskillofskills-ai/techshu-marketplace` then `copilot plugin install contentforge@techshu` | `.github/plugin/plugin.json` (Copilot also recognizes `.claude-plugin/plugin.json` as fallback) | Full skills + MCP support |
| **Google Antigravity 2.0** CLI + IDE | `agy plugin install https://github.com/teachskillofskills-ai/ContentForge-techshu` | `gemini-extension.json` (at repo root, per Google's reference pattern) | Full skills + hooks support |
| **Hermes Agent** (Nous Research) — Desktop + CLI on macOS / Windows / Linux | `hermes plugins install teachskillofskills-ai/ContentForge-techshu` | `plugin.yaml` + `__init__.py` at repo root (Hermes native spec) | Native plugin — adapter walks `skills/` at register time and exposes all 22 skills via `ctx.register_skill()`. Targets Hermes Desktop v0.15.2+ (public preview June 2 2026). |
| **OpenClaw** (formerly Clawdbot / Moltbot) | `openclaw plugins install git:github.com/teachskillofskills-ai/ContentForge-techshu` | `openclaw.plugin.json` at repo root (also auto-detects `.claude-plugin/plugin.json` as Claude-compatible bundle) | Native plugin via `openclaw.plugin.json`; `skills` field points at `./skills`. |
| **Grok** (xAI Build CLI) | `grok plugin install teachskillofskills-ai/ContentForge-techshu` — or add the marketplace: `grok plugin marketplace add teachskillofskills-ai/techshu-marketplace` then `grok plugin install contentforge` (append `--trust` to skip the install confirmation) | `.grok-plugin/plugin.json` + `.grok-plugin/marketplace.json` ([Grok Build](https://docs.x.ai/build/features/skills-plugins-marketplaces) also reads the `.claude-plugin/` manifests for compatibility; the native pair is the first-class lane) | Full skills support; the pipeline runs via the portable execution lane |
| **claude.ai (web)** | Download a hero skill from [the latest release](https://github.com/teachskillofskills-ai/ContentForge-techshu/releases/latest) (e.g. [`cf-brief.skill`](https://github.com/teachskillofskills-ai/ContentForge-techshu/releases/latest/download/cf-brief.skill)) → claude.ai → **Settings → Capabilities** (enable *Code execution and file creation*) → **Customize → Skills → Upload skill** | built from `config/skill-assets.json` by `scripts/build-skill-assets.py` | **Hero skills only** — `cf-brief`, `cf-social-adapt`, `cf-translate`, `cf-video-script`, `cf-aeo-check`. The full pipeline needs subagent dispatch, which claude.ai uploads don't have |
| **Agent Plugins 1.0 hosts** (ChatGPT, Kiro, VS Code, and other adopters of OpenAI's vendor-neutral standard) | via the root `plugin.json` (closed AP1.0 schema) | `plugin.json` at repo root | Skills-only package; `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` accepted everywhere; the **portable execution lane** runs the full pipeline on hosts without subagent dispatch |
**Why this works:** Agent Skills became an open standard in December 2025 (41+ agent products by June 2026). All 22 SKILL.md files in ContentForge are platform-portable as written. The sibling manifests are thin platform-specific wrappers around the same `skills/` directory — no skill duplication.
**Works on 35+ additional Agent Skills platforms** without per-platform manifests — Goose (Block), OpenHands, OpenCode (sst), Junie (JetBrains), Gemini CLI, Roo Code, Cline/Windsurf, Kiro, Amp, Letta, Mux, Factory, Workshop, Tabnine, Mistral Vibe, and more. Point any Agent-Skills-compatible client at `https://github.com/teachskillofskills-ai/ContentForge-techshu/tree/master/skills` and all 22 ContentForge skills are immediately discoverable.
---
## Quick start
### 1. Install the plugin
**In Claude Code (CLI or VS Code/JetBrains extension):**
```bash
/plugin marketplace add teachskillofskills-ai/techshu-marketplace
/plugin install contentforge@techshu
```
**In Anthropic Cowork:**
1. Open the **Plugins** panel in the Cowork UI (sidebar / settings)
2. Click **Add marketplace**, paste `teachskillofskills-ai/techshu-marketplace`
3. After the marketplace syncs, find **ContentForge** in the listed plugins and click **Install**
4. Then run `/contentforge:cf-cowork-setup` once to wire Google Drive as your team's output destination
> ⚠ `/plugin` slash commands work **only in Claude Code (CLI + IDE extension)**. They do NOT work in Cowork, Claude.ai web, or Claude Desktop — use UI navigation in those environments. The `/contentforge:*` skills (like `/contentforge:create-content`) work in all environments where plugins are loaded; only the `/plugin` management family is Claude-Code-only.
### 2. Turn on auto-update (one-time, recommended)
**Third-party marketplaces — including this one — have auto-update OFF by default in Claude Code.** When a newer version is on the marketplace and you're still running an older one, nothing tells you. There's no banner, no badge, no notification. So the first thing to do after install is enable updates:
Open `/plugin`, go to the **Marketplaces** tab, find `techshu`, and toggle **Enable auto-update**. Done — Claude Code will refresh and pull new ContentForge releases at startup from now on, prompting you to run `/reload-plugins` to pick up changes mid-session (no full restart, conversation context preserved).
If you'd rather update manually each time instead, see the [Updating](#updating) section below.
### 3. Set up your first brand
```
/contentforge:brand-setup
```
The agent walks you through brand voice, terminology, guardrails, citation rules, internal-linking site structure, and (if you want commercial impact) the **brand_pages** block — your product/service URLs, conversion CTAs, and authority pages. When you give it a website, it runs a robots-respecting crawler and harvests a verified page inventory in one confirmation step. It saves a `brand-profile.json` to `~/.claude-marketing/<brand-slug>/`.
### 4. Generate content
```
/contentforge:create-content
```
The skill prompts you for content type, brand, topic, target word count, and audience. It then runs 10 phases via specialized subagents (research → fact-check → draft → visuals → validate → proofread → SEO → humanize → review → output), enforces a quality gate after each phase, audits the finished run against its own artifacts, and writes a real `.docx` you can hand to your editor or design team.
### 5. Find your output
ContentForge writes the finished `.docx` to **two** places:
**User-visible copy — this is the one to open:**
```
~/Documents/ContentForge/<brand-slug>/<content-type>/<YYYY-MM>/<slug>.docx
```
This lives in your normal Documents folder, visible in Windows Explorer / macOS Finder / Linux file managers by default. Override the root with the `CONTENTFORGE_PUBLISH_DIR` env var (e.g. point at a Dropbox or team-share path). Run `/contentforge:output-folder` any time to print the absolute path and open the folder in the OS file manager.
**Internal tracking copy — the system-of-record for analytics/audit skills:**
```
~/.claude-marketing/<brand-slug>/tracking/outputs/<YYYY>/<MM-MonthName>/
└── <slug>_v1.0.docx
```
The intermediate phase artefacts (research brief, fact-check report, draft, SEO scorecard, review report, etc.) plus rendered chart PNGs land alongside the tracking copy in the run directory. The `.docx` includes the body, references, and four appendices — **A** SEO Scorecard, **B** Quality Scorecard, **C** Production Details, **D** Internal Link Map.
> **Historical note (fixed in v3.12.3):** earlier versions only wrote to the hidden `~/.claude-marketing/` dotfolder, which Windows Explorer hides by default. Multiple users reported "the file isn't saving on local drive" — it was saving, just somewhere they couldn't see. The dual-copy design is the resolution; `/contentforge:output-folder` is the quick-reveal command.
### 6. If the run gets interrupted, resume it
The 10-phase pipeline runs 20–60 minutes end to end. If the session terminates partway through (context-window exhaustion, network blip, Ctrl-C, machine sleep), every completed phase is saved to disk via `scripts/checkpoint-manager.py`. Resume the run with:
```
/contentforge:resume # auto-picks the most recent in-progress run for the active brand
/contentforge:resume <run-id> # pick a specific run from `checkpoint-manager.py list`
```
The resumer reloads the saved Phase 1..N outputs and continues from Phase N+1 — no re-running phases that already completed. It also reports **orphaned artifacts** (a phase whose artifact exists but was never checkpointed — precisely the window a crash creates), so finished work is verified rather than re-run blind or trusted blind.
### 7. Close the loop (the v4.0 habit)
After you've published a few pieces, three commands turn production into a lifecycle:
```
/contentforge:cf-aeo-check # did AI engines cite the piece? appends to per-brand history
/contentforge:audit-content # score the library for decay; findings recorded durably
/contentforge:cf-calendar --from-audit=latest # next period's plan, fed from the recorded audit
```
Each one writes or reads a durable per-brand file — the loop works across sessions, across weeks, and (with Cowork + Drive) across your whole team. Details in [The content lifecycle loop](#the-content-lifecycle-loop-v40).
---
## What ContentForge does (the 10-phase pipeline)
```
0.5 Title Curation → 4-5 SERP-aware title options; user selects
1 Research → 12-15 verified sources, competitive analysis, site recon + link inventory
2 Fact Checking → URL verification, claim cross-reference → the verified claim ledger
3 Content Drafting → SME-calibrated first draft, every statistic ledger-traceable
3.5 Visual Asset Annotator → deterministic charts from verified data + visual anchors
4 Scientific Validation → hallucination check vs the ledger; corrections filed in the fix ledger
5 Structuring & Proofread → grammar, readability, brand compliance; fix ledger applied BY SCRIPT
6 SEO/GEO Optimization → keyword placements, meta tags, schema, internal links (3 categories, live-verified)
6.5 Humanizer → 43-pattern AI-detection catalog + self-critique + pattern-hit telemetry
7 Review → 5-dimension scoring (Content, Citation, Brand, SEO, Readability)
8 Output Manager → real .docx with embedded scorecards + link map; run audit gates "completed"
```
Each phase has a quality gate **verified by the orchestrator with scripts, never taken from an agent's self-report**. If a gate fails, the orchestrator loops back to the offending phase — max 2 loops per edge, 5 per run, every loop recorded with its reason. All phases run via the **Task** tool against dedicated subagent definitions in `agents/01-researcher.md` through `agents/08-output-manager.md` — there is no single-pass shortcut. On platforms without subagent dispatch, the **portable execution lane** runs the same phases sequentially from the same agent contracts: same artifacts, same gates, same budgets.
The pipeline's shape — every phase's inputs, outputs, gate, and loop target — is declared as data in **`config/pipeline-graph.json`** (v4.0) and drift-guarded against the agent contracts, the checkpoint manager, and the run auditor. A phase asked to verify something its inputs never gave it is now a failing test, not a latent bug.
**And when the last phase ends, the run still has to prove it.** `scripts/run-audit.py` re-derives every claim the finished run makes from the artifacts on disk — completed phases vs artifacts, scaffolding in the delivered body, unanchored assets, corrections lost or undone, an APPROVED decision backed by its own score, a `completed` status hiding a blocked publication. `finalize --status completed` **refuses** without a fresh CLEAN verdict; `--skip-audit` exists as an escape hatch that stamps `audit_skipped: true` into the manifest, because a skipped audit should be a fact on the record, not a silence.
**Realistic timing:** FAQ 30–35 min · article 35–45 min · whitepaper 45–75 min · research paper 60–90 min.
---
## The content lifecycle loop (v4.0)
A pipeline makes a piece. A lifecycle keeps a library alive. ContentForge has had every stage of this loop for a while — what 4.0 adds is the connective tissue that makes it a **system**: every joint is now a file with a schema, so the loop survives the session that ran it.
| Joint | Store (per brand) | Producer → Consumer |
|---|---|---|
| Audit findings | `audits/audit-<date>.json` | `/contentforge:audit-content` records via `scripts/audit-ledger.py` (schema-validated — a malformed record is refused with every problem listed) → `cf-calendar --from-audit=latest` and `content-refresh` read the ranked candidates and recommended scopes by file |
| AI-visibility history | `aeo/checks.json` | `/contentforge:cf-aeo-check` appends every check with deltas → `cf-audit`'s freshness model deducts for lost AI citations (a piece that lost its citations is decaying regardless of its age) |
| Verified brand links | `brand-profile.json` → `brand_pages` | Phase 1's reconnaissance writes `phase-1-link-inventory.json` each run → after Gate 1, the orchestrator merges it via `harvest-brand-pages.py --merge-inventory`. Product/authority pages upsert with freshness stamps; **conversion pages only ever stage for your confirmation** — a CTA is a commercial decision, and the system collects the evidence without making the decision |
| Pipeline learning | `runs/*/phase-6.5-pattern-hits.json` + `runs/*/run.json` | Every run records which humanizer patterns fired and which gate-fail loops ran → `scripts/telemetry.py` aggregates across runs → recurring patterns reach the next Phase 3 brief as advisories, `cf-analytics` shows loop edges and pattern trends |
Three rules keep the loop honest, and they are enforced in code, not intentions:
1. **Absence of measurement is never zero.** A pre-4.0 run without pattern telemetry is `not_instrumented`, not clean; an audit that never saw AEO history says `"n/a — no aeo/checks.json"` in a required field — "not consulted" and "consulted, no signal" can never be the same answer.
2. **Learning has floors.** Telemetry advisories require a recurrence floor (default: a pattern seen in ≥3 instrumented runs) before a word of them reaches a brief. Below the floor the answer is `insufficient_history` and nothing is advised — a brief fed from fewer runs than the floor is fed from anecdote.
3. **Loops inform; they never gate.** Advisories shape drafting style and dashboards. They are forbidden — by contract and by test — from modifying a gate, a threshold, or a verdict. The quality machinery stays human-set and re-derived.
On **Cowork**, these stores ride the same Drive sync as brand profiles and checkpoints (`/contentforge:cf-cowork-setup`). Without Drive routing, the Cowork sandbox forgets them at session end — the loop still works within a session, but compounding across sessions is most of its point, so teams should treat Drive routing as required.
---
## Internal linking — the three categories
ContentForge is a **marketing system**, not a search-engine pipeline. Informational links alone don't drive any commercial outcome. Links are scored in three independent categories:
| Category | What it does | Brand profile field |
|---|---|---|
| **Topical** (informational) | Link to related content on the brand's own site | `seo_preferences.internal_linking.{sitemap_url,page_registry,pillar_pages}` |
| **Commercial** (revenue) | Link a natural anchor in the body to the brand's product/service/program page | `seo_preferences.brand_pages.product_or_service_pages` |
| **Conversion** (funnel handoff) | One audience-matched CTA near the end (request MSL, book demo, talk to sales, subscribe) | `seo_preferences.brand_pages.conversion_pages` |
| **Authority** (optional) | Hyperlink the brand's first name occurrence to the about / leadership page | `seo_preferences.brand_pages.authority_pages` |
The SEO agent emits typed `<!-- INTERNAL-LINK: type=... | anchor=... | url=... -->` markers; the .docx generator renders each as a real Word hyperlink, **color-coded by type** (topical blue, commercial green, conversion purple, authority slate). Where the brand has not provided a URL, the marker stays as a visibly-distinct red `[anchor] [LINK TBD: type]` placeholder — the human reviewer fills it in before publication, instead of the link opportunity being silently skipped.
**Auto-harvest:** `/contentforge:brand-setup` runs `scripts/harvest-brand-pages.py` against the brand's website — a stdlib, robots-respecting crawler that returns an HTTP-verified page inventory (service/conversion/authority pages) plus verbatim `brand_facts` (one source URL per fact; where pages disagree, both versions are kept with an `inconsistency_note` for you to resolve, never silently merged). One confirmation step and it's saved straight into the `brand_pages` block. If you decline, the crawl fails, or the brand genuinely has no site, `harvest_status` records exactly which — honestly, never as a silent skip.
**And from v4.0, the inventory stays alive:** every pipeline run re-verifies deep brand URLs during Phase 1 reconnaissance, and the orchestrator merges the verified rows back into `brand_pages` after Gate 1 — freshness stamps updated, new pages added with provenance, your manual curation never overwritten, and conversion candidates staged (never activated) for your review under `brand_pages.recon_candidates`.
**Deep-link rule + thin-`brand_pages` guard:** the researcher (Phase 1) builds a live Internal-Link Inventory of deep brand URLs the piece could naturally reference, HTTP-verified on the day of the run. Phase 6 requires **≥2 deep links** (not just the homepage) whenever the brand's site has them — if `brand_pages` is empty or homepage-only, Phase 6 falls back to that Phase 1 inventory, then a just-in-time sitemap fetch, instead of silently skipping commercial linking.
**Configure once per brand:**
```json
"seo_preferences": {
"internal_linking": {
"page_registry": [
{"url": "https://yoursite.com/resources/your-pillar-guide", "topic": "pillar topic", "type": "pillar"}
],
"pillar_pages": ["https://yoursite.com/resources/your-pillar-guide"]
},
"brand_pages": {
"product_or_service_pages": [
{"url": "https://yoursite.com/programs/access", "topic": "patient access program", "category": "program",
"anchor_text_hints": ["access program", "affordability assistance"]}
],
"conversion_pages": [
{"url": "https://yoursite.com/contact/msl", "purpose": "request MSL", "audience": "HCP",
"anchor_text_hints": ["request a Medical Science Liaison consult"]}
],
"authority_pages": [
{"url": "https://yoursite.com/about/medical-affairs", "purpose": "medical affairs leadership", "audience": "HCP"}
]
}
}
```
The reviewer (Phase 7) scores 6a Topical / 6b Commercial / 6c Conversion **independently**. Categories the brand has not configured score N/A and don't penalize — but a brand **with** a website whose `brand_pages` was never harvested is a scored deficiency, not an N/A free-pass; homepage-only linking caps the 6b sub-score with a mandatory finding; and any dead internal-link URL is a hard publish-blocking FAIL. The agent must produce useful link markers (real URLs or placeholders) to earn credit.
> See `config/brand-registry-template.json` for the full schema.
---
## Examples
### Run a real white paper — worked example
```
/contentforge:create-content
```
When prompted, supply:
- **Brand:** `acme-pharma` (must already exist via `/contentforge:brand-setup`)
- **Content Type:** `whitepaper`
- **Topic:** `Pharmacovigilance for HER2-Directed ADCs in Community Oncology`
- **Target Audience:** Community medical oncologists, oncology pharmacists
- **Word Count:** 3500-4200
- **SEO Keywords:** `ADC pharmacovigilance, T-DXd ILD monitoring`
The pipeline runs ~60 min. When it finishes you get a `.docx` in `~/Documents/ContentForge/acme-pharma/whitepaper/<YYYY-MM>/`. Open it in Word: the body, the references, then **Appendix A** (SEO scorecard with keyword placements, meta tags, schema), **Appendix B** (5-dimension quality scorecard), **Appendix C** (production details — phase timings, source reliability, accuracy figures with their phase attributions), and **Appendix D** (internal link map showing every topical / commercial / conversion / authority link the agent placed, with target URLs and anchor text). All inline hyperlinks are clickable in Word.
### What a real gated run looks like — from a live validation run
This is an actual run (August 2026, a digital-preservation test brand, 1,200-word blog, keyword "link rot") — reported exactly as it happened, because the failure-catching is the product:
- **Phase 2 caught Phase 1 misreading a statistic.** The research summarized a source as "the Wayback Machine recovers ~16% of dead URLs"; the fact-checker read the primary source, found 16% was a share of the *entire dataset* (not of dead URLs), locked corrected wording into the verified ledger, and **banned the original sentence from the draft**. The correction survived — verbatim — through six more phases into the delivered Word file, with the disambiguation printed for the reader.
- **Phase 4 diffed 42 claims against the ledger: zero hallucinations**, one minor citation-placement correction — filed in the fix ledger, applied *by script* at Phase 5, and verified still intact at Phases 6.5, 7, and 8.
- **Phase 7 approved at 9.0/10** — and honestly sub-scored internal linking down because the test brand had no `conversion_pages` configured, naming the config gap instead of hiding it.
- **Phase 8's Appendix C corrected a number the orchestrator supplied.** Asked to print "source reliability 8.1", the output manager recomputed it from the research artifact, got 7.9, and printed 7.9 with its reasoning. The honesty discipline binds in every direction.
- **The run auditor re-derived all of it** — 14 checks passed, 0 failed — and only then did `finalize --status completed` accept the run.
Single-prompt tools produce none of these paper trails. The point isn't that the pipeline never errs — it's that its errors get caught by its own machinery, on the record, before your editor ever sees the file.
### The artifacts themselves — real output you can inspect
Everything below is from that same run — not a mock-up, not a demo. The numbers are read from the run's own JSON artifacts (`phase-7-review.json`, `run-audit.json`, `phase-6.5-report.md`, `pipeline-run.json`):
**A chart the pipeline actually rendered** (Phase 3.5 annotates the visual opportunity from verified Phase 2 data; a stdlib matplotlib-free renderer produces the PNG; the data citations ride in the caption):
**The opening the reader actually gets** (from the delivered file — note there's no "In today's digital landscape" anywhere in sight):
> 38% of webpages that existed in 2013 are not available today (Chapekis et al., 2024). Not redesigned. Not moved. Gone. The same Pew study found that 21% of government webpages contain at least one broken link.
>
> The uncomfortable part is the cause, not the scale. When institutional pages disappear, the trigger is usually organizational rather than slow technical decay: a CMS (content management system) migration that dropped a URL structure, or a decision to take pages down. That has a practical upside: events can be planned for, and decay can't.
**What the humanizer actually did to earn that opening** — three of the 20 logged edits, verbatim from the Phase 6.5 report (every edit records before → after, and whether SEO placements survived):
| Pattern | Before | After |
|---|---|---|
| #09 negative parallelism | "link rot isn't a distant hazard, it's already on the premises" | "For public institutions, link rot is already on the premises." — the contrast now rides on "already" |
| #28 signposting | a 38-word roadmap sentence ("What follows is the evidence: …") | **DELETED** (logged in the Deletion Ledger — announcements that the next part matters never survive) |
| #14 em-dash overuse | 14 em dashes (~5.4 per 500 words) | 5 (~1.9 per 500) — nine converted to periods, commas, colons, parentheses; the two kept include a dash-gloss pair that matches the brand's own writing sample, which the voice calibration step protected |
**And the honesty layer, in one JSON excerpt** — the run auditor's verdict that gated `finalize --status completed`:
```json
{
"run_id": "20260816-131632-link-rot-…",
"pass": 14, "fail": 0, "na": 1,
"verdict": "CLEAN"
}
```
One more real detail worth knowing: Phase 8 was killed twice mid-run by session limits. Both times the checkpoint contract resumed it from the artifacts on disk — the delivered `.docx` exists because resume is a contract, not a hope. (The run brand is an internal validation persona for the digital-preservation space, not client work — which is why we can show you its artifacts.)
### Close the loop on a growing library
```
# After a month of publishing:
/contentforge:cf-aeo-check # record which pieces AI engines cite (history + deltas)
/contentforge:audit-content # freshness-score the library; the findings are RECORDED
/contentforge:cf-calendar --period=90 --from-audit=latest # next quarter: refreshes + gaps, from data
/contentforge:content-refresh # execute a refresh at the audit's recommended scope
```
Every command reads what the previous one recorded — in a new session, on a different day, by a different teammate.
---
## Commands (visible in the Customize sidebar)
These 9 commands are the user-facing entry points:
| Command | What it does |
|---|---|
| `/contentforge:create-content` | Run the full 10-phase pipeline for a single piece |
| `/contentforge:content-brief` | Generate a research-backed brief with keyword data, competitor analysis, outline |
| `/contentforge:social-adapt` | Repurpose an article into LinkedIn / Twitter / Instagram / Facebook / Threads posts |
| `/contentforge:publish` | Push to Webflow or WordPress with preview, verification, HTML fallback |
| `/contentforge:translate` | Translate into 15+ languages preserving brand voice, citations, SEO |
| `/contentforge:brand-setup` | Configure brand voice, terminology, guardrails, internal linking, **brand_pages** (with auto-harvest) |
| `/contentforge:audit-content` | Audit content library for freshness decay and coverage gaps — findings recorded to the durable audit ledger (v4.0) |
| `/contentforge:output-folder` | Print + open the user-visible output folder (`~/Documents/ContentForge/<brand>/`) — answers "where did my file go?" |
| `/contentforge:resume` | Resume an interrupted pipeline run from the last completed phase instead of starting over |
> Slash command syntax is canonical `/<plugin-name>:<command>` — the older `/cf:` shortcuts no longer work as of v3.9.3.
---
## Skills (run via the Skill tool — superset of commands)
| Skill | Purpose |
|---|---|
| `contentforge` | Full 10-phase production (the default skill the `/contentforge:create-content` command invokes) |
| `batch-process` | Process 10–50+ pieces as a sequential, checkpointed queue — survives interruption, resumes mid-piece |
| `content-refresh` | Update old content with current data, preserve SEO — reads recorded audit candidates by file (v4.0) |
| `cf-brief` | Research-backed brief with keyword analysis and outline |
| `cf-audit` | Freshness scoring, decay detection, gap analysis — records findings to `audits/` via `audit-ledger.py`, consumes AEO history (v4.0) |
| `cf-calendar` | Production scheduling with deadline tracking — imports refresh slots from the recorded audit (v4.0) |
| `cf-style-guide` | Import brand voice, generate brand profile JSON |
| `cf-template` | Create custom content type templates beyond the 8 built-in |
| `cf-variants` | Generate 3–10 headline / hook / CTA variations with scoring |
| `cf-analytics` | Quality trends, timing breakdown, brand performance — plus loop-edge and humanizer-pattern telemetry panels (v4.0) |
| `cf-translate` | Translate preserving brand voice (15+ languages, 3 levels) |
| `cf-video-script` | Timestamped scripts for YouTube / TikTok / Instagram Reels |
| `cf-social-adapt` | Article → social media platform-specific posts |
| `cf-publish` | Push to Webflow / WordPress |
| `cf-integrations` | Dashboard of connected vs. available connectors |
| `cf-connect` | Guided setup for any of 22 supported connectors |
| `cf-add-integration` | Add a custom MCP connector for any API |
| `cf-switch-backend` | Switch tracking backend (local / Airtable / Google) with optional data migration |
| `cf-help` | User guide, pipeline overview, examples, troubleshooting |
| `cf-aeo-check` | Post-publication AI-citation check — AI Overview presence, own-citation status, extractability audit, append-only per-brand history with deltas |
| `cf-cowork-setup` | One-time Cowork + Google Drive wiring so team runs — and the v4.0 lifecycle stores — persist across sessions |
| `cf-environment` | Detect the runtime environment and show its capability matrix |
---
## Architecture
### 13 agents
| Phase | Agent | Purpose | Avg Time |
|---|---|---|---|
| 1 | Researcher | SERP analysis, source mining, outline, site recon + link inventory | 6–8 min |
| 2 | Fact Checker | URL verification, claim cross-reference → verified ledger | 4–6 min |
| 3 | Content Drafter | First draft with brand voice + SME calibration | 4–6 min |
| 3.5 | Visual Asset Annotator | Chart generation, visual anchors, asset manifest | 3–9 min |
| 4 | Scientific Validator | Hallucination detection, domain validation, fix ledger | 3–9 min |
| 5 | Structurer & Proofreader | Grammar, readability, brand compliance, ledger application | 2–7 min |
| 6 | SEO/GEO Optimizer | Keywords, meta tags, AI Overview, **3-category internal linking** | 3–8 min |
| 6.5 | Humanizer | 43-pattern AI-detection catalog + self-critique meta-pass + pattern telemetry | 5–8 min |
| 7 | Reviewer | 5-dimension scoring with comparative ranking | 1–4 min |
| 8 | Output Manager | `.docx` with hyperlinks, charts, scorecards, link map | <1 min |
| 9 | Batch Orchestrator | Sequential, checkpointed queue coordination | post-pipeline |
| 10 | Social Adapter | Platform-specific repurposing | post-pipeline |
| 11 | Translator | Brand voice mapping, cultural adaptation | post-pipeline |
### The pipeline graph (v4.0)
`config/pipeline-graph.json` is the machine-readable form of the pipeline contract: nodes are phases, edges are the file-based handoffs, loop targets carry their budgets. `tests/test_pipeline_contract_graph.py` fails the build if the graph, the agent contracts, the orchestrator's table, `checkpoint-manager.py`, or `run-audit.py` ever disagree — in either direction. Encoding the contract as data immediately surfaced six inputs the prose table had under-declared (including one the agent file itself annotated as "was missing from this list" after a previous drift incident). The portable execution lane and the resumer walk this graph rather than re-deriving the order from prose.
### Quality scoring (Phase 7 reviewer, 5 dimensions)
| Dimension | Weight | What it measures |
|---|---|---|
| Content Quality | 30% | Depth, originality, audience value, structure, completeness |
| Citation Integrity | 25% | Factual accuracy, source quality, formatting, recency |
| Brand Compliance | 20% | Voice/tone, terminology, guardrails, POV consistency, industry compliance |
| SEO Performance | 15% | Keywords, meta tags, on-page SEO, GEO, schema, **internal linking (6a/6b/6c split)** |
| Readability | 10% | Reading level, sentence variety, paragraph structure, scannability, humanization |
Decision thresholds: **9.0+ A** publish + repurpose · **7.0–8.9 B** publish · **5.0–6.9 C** loop back · **<5.0 D** human escalation. Thresholds, weights, dimension minimums, and industry overrides live in `config/scoring-thresholds.json` — the single source of truth; where prose and config disagree, the config wins.
### Three-layer fact verification
Single-pass fact-checking misses 15–20% of hallucinations. ContentForge uses three independent layers — Phase 2 (Fact Checker) verifies sources before drafting and builds the verified claim ledger, Phase 4 (Scientific Validator) re-diffs the draft against that ledger claim by claim, Phase 7 (Reviewer) audits factual accuracy as part of holistic scoring. Corrections travel in a machine-verified **fix ledger** (`phase-4-fixes.json`): applied by script at Phase 5, guarded so a style pass cannot undo an accuracy fix, re-verified at every later phase, and enforced at Phase 8 — unresolved blocking corrections don't stop the document being produced; they stop it being called ready (`DRAFT-` prefix, named blockers, blocked tracking status).
### The run auditor
`scripts/run-audit.py` re-checks a finished run the way an outside auditor would: every completed phase has its artifact, no orphaned artifacts in a finalized run, the delivered body carries no production scaffolding and anchors every generated asset, the authorship record matches a fresh measurement, no fix-ledger correction was lost or undone, an APPROVED decision is backed by its own score, and no `completed` status hides a blocked publication. Every check corresponds to a failure that actually happened in a real run while every individual artifact looked healthy. Two disciplines throughout: **re-derive, never trust** (gate fields are compared against fresh script output), and **a missing input is reported-N/A, never silent-pass**.
### Industry knowledge packs
10 domain-specific configs at `config/industries/` (pharma, BFSI, healthcare, legal, real estate, technology, B2B SaaS, e-commerce, consumer goods, education) calibrate the Content Drafter as a subject-matter expert and give the Scientific Validator domain-specific terminology, evidence standards, regulatory rules, and common pitfalls to check against. A brand whose industry has no pack gets an honest "generic writing mode" declaration that travels to the reviewer — never a silent pretense of expertise.
### Phase 6.5 Humanizer (the differentiator)
43-pattern AI-detection catalog (7 buckets: content, language/grammar, style, communication, filler/hedging, structure/framing, detector-signal) adapted from Wikipedia: Signs of AI Writing + blader/humanizer. Includes a self-critique meta-pass ("what makes this still obviously AI?") and optional voice calibration from a brand `writing_sample` field.
**Grounding-first, not trick-first.** The old move — inserting short punchy sentences to raise the burstiness number — is gone: it manufactured the exact aphoristic-maxim tell modern detectors flag. In its place, a **Human-Expert Grounding Pass** grounds every standing maxim, impersonal assertion, and flat-confidence claim in a specific from the Phase 2 verified ledger — or removes it; nothing is invented for style. Sentence variety is **content-derived**: uniform runs get broken by material the content already earns, never by content-free filler. Burstiness is reported as advisory context, not a pass/fail gate. Significance markers ("here's the thing", "let that sink in") are **deleted, never reworded**. When an author supplies their own draft (`--source-draft`), their sentences are carried verbatim, exempt from the catalog, and `scripts/authorship.py` **blocks** if any were paraphrased or dropped — the one hard check in the phase, because "the author wrote this and it is gone" is a fact, not a probability.
**Advisory `--ai-tell-scan`.** `scripts/text-metrics.py --ai-tell-scan` runs a deterministic, zero-dependency proxy scan (aphorism density, banned lexemes, connective/participial-opener rate, uniform sentence runs) and reports a **LOW / MODERATE / HIGH** advisory rating — surfaced in the Phase 6.5 report, the reviewer's Readability sub-score, and the Completion Card. It is never a publish gate, and ContentForge never claims to "beat" any specific detector — see the [FAQ](#faq) and `references/ai-detection-signals.md` for the full reasoning.
**And from v4.0 the phase reports what it fixed, durably:** `phase-6.5-pattern-hits.json` records per-pattern fire counts for `scripts/telemetry.py`, so a pattern your brand's drafts keep producing eventually reaches the drafter's brief as an advisory — behind the recurrence floor, never as a gate. The pipeline stops re-making mistakes its own quality machinery keeps catching.
### Model curator — no hardcoded model ids
Frontier models change every ~6 weeks. ContentForge ships a shared registry + resolver so model ids are never hardcoded across scripts: edit `scripts/model_registry.json` in one place and every script picks up the change next call. Aliases resolve at call time; deprecated ids auto-fall-forward to their replacement; `scripts/refresh_models.py` polls live provider catalogs and reports drift. See [`docs/MODEL-CURATOR.md`](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/docs/MODEL-CURATOR.md).
```bash
python scripts/resolve_model.py --alias latest-balanced-anthropic
python scripts/resolve_model.py --check <some-old-model-id> # warns when deprecated + names the replacement
```
### Where your data lives
```
~/.claude-marketing/<brand-slug>/
├── brand-profile.json # voice, terminology, guardrails, brand_pages (+ recon_candidates)
├── runs/<run-id>/ # per-run artifacts, checkpoints, fix ledger, run-audit.json, telemetry
├── audits/ # recorded cf-audit findings (v4.0) — what the calendar reads
├── aeo/checks.json # append-only AI-visibility history (per-check deltas)
├── tracking/outputs/ # the internal system-of-record .docx copies
└── output/ # intermediate artifacts + rendered charts
```
Plus the user-visible deliverables in `~/Documents/ContentForge/<brand>/`. Everything under the brand directory rides Drive sync on Cowork once `/contentforge:cf-cowork-setup` has run.
---
## Connectors (MCP integrations)
ContentForge ships with **9 HTTP connectors** that work in both Cowork and Claude Code: Notion, Canva, Figma, Webflow, Slack, Gmail, Google Calendar, fal.ai (AI image generation), Replicate (AI image generation). All are **opt-in** — the plugin works fully without any connectors and produces output locally.
For Cowork users who need Google Sheets / Drive / and ~1000 other SaaS services that have no first-party HTTP MCP, see `.mcp.json.connectors-reference` for Pipedream / Composio / Zapier / Make.com aggregator paths.
For Claude Code users who want stdio MCPs (Google Sheets via service account, Google Drive, etc.), copy the example config:
```bash
cp .mcp.json.example .mcp.json
```
See [CONNECTORS.md](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/CONNECTORS.md) for the full reference.
---
## Troubleshooting
### Pipeline stops early in `--print` / one-shot mode
`claude --print` exits at the first interactive prompt (e.g., title selection). When scripting non-interactive runs, **pre-supply every input** in the prompt — including the title selection from Phase 0.5.
### Pipeline didn't actually invoke subagents (everything happened "in one inference")
Verify v3.9.4 or later is installed (`claude plugin list`). Pre-v3.9.4 versions had a SKILL.md bug that allowed single-pass generation. The fix mandates Task-tool dispatch per phase. On platforms with no Task dispatch at all, the portable execution lane is the supported mode — sequential, same gates.
### `finalize --status completed` was refused
Working as designed: the run auditor found something the artifacts don't support — the refusal lists the failing checks and the recovery options. Fix the findings and re-run `scripts/run-audit.py`, or finalize honestly as `blocked` if the run is legitimately unpublishable as it stands. `--skip-audit` exists but stamps `audit_skipped: true` into the record.
### `cf-calendar --from-audit=latest` says no recorded audits exist
The calendar reads recorded audits (`audits/`), not conversations. Run `/contentforge:audit-content` first — since v4.0 it records its findings via `audit-ledger.py` as the final, required step. An audit rendered but not recorded did not happen, as far as the lifecycle is concerned.
### `.docx` has no internal links
Check your brand profile has `seo_preferences.internal_linking.page_registry` (or `sitemap_url`) populated. For commercial and conversion links, populate `seo_preferences.brand_pages.product_or_service_pages` and `conversion_pages`. If those are empty, the agent has nothing to link to. Re-run `/contentforge:brand-setup` to fill them in — or, from v4.0, just run the pipeline: verified pages found during research merge back into the profile automatically (conversion pages staged for your confirmation under `brand_pages.recon_candidates`).
### Pipeline fails at Phase 1 (Research)
Topic too niche, no search volume, or `WebSearch` not enabled. Broaden the topic or use a related keyword with more search volume.
### Content score below 7.0 and keeps looping
Review Phase 7 Quality Scorecard for the weakest dimension. Most common cause: weak brand profile. Run `/contentforge:brand-setup` and verify voice, guardrails, and audience are filled in. For regulated industries (pharma, BFSI, healthcare, legal) the threshold is 8.0 and guardrails are required. Loops are budgeted (2 per edge, 5 per run) — at the limit the run stops for human review instead of burning tokens. If the same edge keeps firing across runs, check `cf-analytics`'s loop panel: a recurring edge is a contract/template problem, not a run problem.
### Phase 6.5 Humanizer degrades SEO
Expected — the humanizer auto-loops back to Phase 6 once if SEO degrades, and the second pass usually balances both.
### Connector not working
Run `/contentforge:cf-integrations` to check status. Run `/contentforge:cf-connect <name>` for guided setup.
### Manifest install error: "repository field is an object" or "$schema unknown"
Fixed in v3.9.2. Update: `claude plugin marketplace update techshu && claude plugin update contentforge@techshu`.
### `/cf:` shortcut commands no longer work
As of v3.9.3 the canonical namespace is `/contentforge:`. The `/cf:` prefix was removed in the namespace sweep — use `/contentforge:create-content`, `/contentforge:brand-setup`, etc.
---
## Updating
> **If you see "/plugin isn't available in this environment"** — you're in Cowork, Claude.ai web, or the Claude Desktop app. The `/plugin` slash command for plugin management is **only** supported in **Claude Code** (CLI + IDE extension at [claude.com/code](https://claude.com/code), `npm install -g @anthropic-ai/claude-code`). Everywhere else — Cowork, `claude.ai`, Claude Desktop, mobile — plugins are managed through the UI panel, not slash commands.
>
> The plugin IS installed (your `/contentforge:*` skills still work in chat); only the management command is unavailable. Fix:
>
> 1. **In Cowork** — open the **Plugins** panel (sidebar / Settings → Plugins). Find ContentForge → look for Update / Refresh. If there's no Update option, **Remove** the plugin, then re-install it from the `techshu` marketplace — the re-pull fetches the latest version. If the marketplace itself is stale, also Remove + re-add the marketplace.
> 2. **In Claude.ai web or Claude Desktop** — same UI flow as Cowork: open the chat's Plugins UI button at the bottom → **Manage plugins** → Remove + Add to re-pull.
> 3. **For slash-command management** — switch to **Claude Code (CLI or IDE extension)**. The plugin runs identically across every Anthropic surface; you're choosing where to type management commands.
>
> Once you're in Claude Code, the rest of this section applies.
**Third-party marketplaces (including this one) have auto-update DISABLED by default in Claude Code.** Anthropic's official marketplace updates itself; ours does not. So when a newer version is on the marketplace and you're still running an older one, nothing tells you — there is no update banner, no badge, no notification.
You have two options:
### Option 1 (recommended) — turn auto-update on for our marketplace once
Run `/plugin`, go to the **Marketplaces** tab, find `techshu`, and toggle **Enable auto-update**. From then on, Claude Code refreshes the catalog at startup and pulls the latest ContentForge automatically. After an auto-update fires you'll be prompted to run `/reload-plugins` to pick up the changes mid-session.
### Option 2 — manual update each time
```
/plugin marketplace update techshu
/plugin uninstall contentforge@techshu
/plugin install contentforge@techshu
/reload-plugins
```
`/reload-plugins` applies the change without a full Claude Code restart and preserves your current conversation context.
### If a version stays the same but content changed
This happens during fast-iteration debugging. Clear the cached copy and reinstall:
```
rm -rf ~/.claude/plugins/cache/techshu
/plugin install contentforge@techshu
/reload-plugins
```
### Updating on every other surface
The sections above cover Claude Code because that's where update *management* has the most footguns (the auto-update default). Everywhere else, updating is one command or one UI action:
| Surface | How to update |
|---|---|
| **Anthropic Cowork** | Plugins panel → ContentForge → **Update** (or Remove + re-install from `techshu` — the re-pull fetches latest). If the marketplace itself is stale, Remove + re-add the marketplace too. |
| **claude.ai web / Claude Desktop** (plugin) | Plugins UI button at the bottom of the chat → Manage plugins → Remove + Add to re-pull. |
| **claude.ai web** (hero `.skill` uploads) | Re-download the skill from the [latest release](https://github.com/teachskillofskills-ai/ContentForge-techshu/releases/latest) and re-upload — uploaded skills never self-update. |
| **OpenAI Codex** | `codex plugin update contentforge` |
| **Cursor 2.5+** | Re-run `/add-plugin contentforge@https://github.com/teachskillofskills-ai/ContentForge-techshu` — it re-pulls the repository. |
| **GitHub Copilot CLI** | `copilot plugin update contentforge` |
| **Google Antigravity 2.0** | `agy plugin update contentforge` |
| **Hermes Agent** | `hermes plugins update contentforge` (then `hermes plugins list` to confirm the version) |
| **OpenClaw** | `openclaw plugins update contentforge` |
| **Grok (xAI Build CLI)** | `grok plugin update contentforge` |
After any update, the fastest sanity check on every surface is asking the agent: *"What version of ContentForge is installed?"* — `scripts/plugin-metadata.py` answers from the installed manifest, not from memory.
### Upgrading from 3.x to 4.x
No breaking changes to existing runs, brands, or artifacts — 4.x is additive. Pre-4.0 runs simply read as `not_instrumented` in telemetry (unknown, never zero), and the first recorded audit starts the lifecycle stores. See [UPGRADE-GUIDE.md](https://github.com/teachskillofskills-ai/contentforge-techshu/blob/HEAD/UPGRADE-GUIDE.md).
### Installs in Cowork
Cowork is the Anthropic Desktop computer-use product (macOS/Windows). It supports third-party plugins from custom marketplaces — same `/plugin marketplace add` install pattern. Cowork has local filesystem access, so the full ContentForge pipeline including the `generate-docx.py` step runs and produces real `.docx` files, just as in Claude Code CLI/Desktop. The only Cowork limitation that affects ContentForge is **HTTP MCPs only** (no stdio/npx) — which is why our `.mcp.json.connectors-reference` documents Pipedream / Composio / Zapier / Make.com aggregator paths for any service that doesn't ship a first-party HTTP MCP.
---
## FAQ
**Q: How does ContentForge compare to ChatGPT or Claude directly?**
Single-prompt tools produce content in 30 seconds with ~15–20% hallucination rate, generic voice, and visible AI patterns. ContentForge takes 35–60 minutes but applies three-layer fact verification, brand voice calibration, AI-pattern removal, dimensioned quality scoring, and a run audit that re-derives every gate before the run may call itself finished. Each piece comes with a transparent scorecard — and from 4.0, each brand gets a lifecycle: published pieces are measured, decay is detected, and the next plan is fed from data.
**Q: Can I use ContentForge without Google Drive / Sheets?**
Yes. Three tracking backends: Google Sheets + Drive, Airtable, or local filesystem. Local works zero-config. Switch any time with `/contentforge:cf-switch-backend`.
**Q: How much does it cost to run?**
Plugin is MIT-licensed and free. Claude API costs are typically $1–4 per piece depending on length and how many quality-gate loops are needed.
**Q: What content types are support 
