Collections & Generation

Collections are the unit of work in pSEO: a schema + niches + templates that produce pages at scale.

What Is a Collection?

A collection is a generation job definition that combines a content schema with one or more niches to produce pages. When you run a collection, the engine cross-multiplies your selected niches and their subtopics, deduplicates against existing pages, queues AI generation jobs, validates the output, and publishes the results.

Each collection belongs to a project and stores:

• A reference to a content schema (what structure to generate)
• A set of niches (who the content targets)
• A URL pattern (how page URLs are built)
• A title template (deterministic page titles)
• Publishing mode (when pages go live)

Creating a Collection

Run the interactive wizard or pass flags directly. The wizard walks you through:

1. Choose a schema — Select from the 10 built-in schemas or your custom ones.
2. Select niches — Pick one or more niches. Each niche's subtopics expand the page count.
3. Configure URL pattern — Define the URL slug template using tokens.
4. Set title template — Inherited from the schema's TitlePattern, but can be overridden.
5. Choose publishing mode — immediate, batched, or manual (pair with cron for scheduled releases).
6. Review & generate — Preview the expected page count and confirm.

Or pass the flags directly for non-interactive use (CI, agents):

contento collections create \
    --project proj_8f3a... \
    --schema "idea-list" \
    --niches "niche_01...,niche_02..."

contento collections generate col_9d2f...

  Generating 40 pages across 2 niches...
  [00:26] ████████████████ 40/40 (100%)
  Validation: 38 passed, 2 retried, 0 failed

URL Pattern Tokens

The urlPattern field accepts these tokens, which are replaced for each generated page:

Token	Replaced With	Example Output
{niche}	Niche slug	developer-tools
{subtopic}	Subtopic slug (kebab-case)	ci-cd-pipelines
{year}	Current year	2026
{count}	Item count from schema	10

Example: /{niche}/{subtopic}-ideas-{year} produces /developer-tools/ci-cd-pipelines-ideas-2026.

Title Template

Titles are deterministic and never AI-generated. The title template uses the same tokens as the URL pattern. This ensures every page has a SERP-optimized title that matches the user's search intent exactly.

Example: {count} {subtopic} Ideas for {year} produces 10 CI/CD Pipelines Ideas for 2026.

Subtopic Expansion

When a collection runs, each niche contributes its list of subtopics. The engine forms a cross-product:

# 2 niches with 20 subtopics each = 40 pages
niche: Developer Tools   (20 subtopics)
niche: DevOps            (20 subtopics)
schema: Idea List
= 40 unique pages

Before queuing, the engine deduplicates against all existing pages in the project to avoid generating duplicate content for subtopics already covered.

Generation Pipeline

The pipeline runs these stages in order:

1. Expand — Cross-multiply selected niches with their subtopics to produce a candidate page list.
2. Deduplicate — Compare candidate URLs against existing pages in the project. Skip already-generated pages.
3. Queue — Add remaining candidates to the Redis-backed job queue.
4. Generate — Concurrent workers (default: 10) dequeue jobs and call the AI with the assembled prompt (niche context + schema + prompt template).
5. Validate — Check the AI output against schema validation rules (item counts, lengths, required fields, JSON validity).
6. Publish — Valid pages are rendered to HTML using the schema's renderer and published according to the collection's publishing mode.
7. Link — Internal links are injected between related pages within the project for SEO interlinking.

Concurrent Workers

The concurrentWorkers setting controls how many AI generation jobs run in parallel. The default is 10. You can increase this to speed up large batches or decrease it to stay within AI API rate limits.

Setting	Pages/Hour (approx.)	Use Case
5	~150	Conservative, low API rate limit
10 (default)	~300	Standard generation
20	~600	Large batch, high API tier

Retry Logic

If AI generation or validation fails for a page:

1. The generator retries once with an adjusted prompt (including the validation error message).
2. If the retry also fails, the page is marked as failed and logged with the error details.
3. Failed pages can be inspected with contento collections show <id> --status failed and re-run with contento collections regenerate <page-id>.

Monitoring Progress

The CLI shows a real-time progress bar during generation. For machine-readable output, use --json to get NDJSON streaming:

contento collections generate col_9d2f... --json

{"type":"progress","current":12,"total":40,"done":false}
{"type":"progress","current":28,"total":40,"done":false}
{"type":"progress","current":40,"total":40,"done":true}

Publishing Modes

Mode	Behavior
Immediate	Pages go live as soon as they pass validation. Best for initial launches.
Batched	Pages accumulate and are published in configurable batches (e.g., 50 per day). Avoids triggering Google's "spam burst" detection.
Scheduled	All pages in the collection are published at a specified future date/time.
Manual	Pages are generated but held in draft. You review and publish individually or in bulk.

CLI Commands

Command	Description
contento collections list	List all collections for a project
contento collections create	Create a new collection
contento collections generate	Create a collection and start generation
contento publish	Publish pages from a collection

See the CLI reference for all available flags and options.