Build a source that can prove it works.

AI prompt

Give your coding agent the complete job.

Enter a website, choose its content type, and generate a master prompt for Codex, Claude, Gemini, Cursor, or another coding agent. The prompt links to one canonical public tester and requires honest evidence.

Workflow

Inspect, implement, prove, publish.

1. Inspect the source. Record real request paths, redirects, pagination, content type, access requirements, and terms before coding.
2. Create stable identities. Choose an immutable module ID and family ID, then use semantic versions for every behaviour change.
3. Implement the smallest contract. Declare only the handlers, hosts, and capabilities the source actually needs.
4. Add sanitized fixtures. Cover valid, empty, malformed, paginated, duplicate, blocked, and terminal-content responses.
5. Run escalating evidence. Contract, fixture, bounded live Node, then iOS WebKit where available.
6. Finalize and publish. Bump version, generate hashes, validate, commit, and add the repository URL in Books.

Repository

Loose files, installed from GitHub.

index.json
modules/
  example-source/
    manifest.json
    index.js
    icon.png
    fixtures/
      expected.json
      search.html
      details.html
      chapters.html
      images.html

ZIP files, APKs, remote scripts, and generated binaries are not part of the Books source format. Every path resolves relative to index.json.

Manifest

Declare identity, access, and limits.

{
  "id": "example-source-v1",
  "familyID": "example-source-v1",
  "version": "1.0.0",
  "contractVersion": 1,
  "contentType": "pageImages",
  "capabilities": ["discovery", "search", "details", "chapters", "images"],
  "baseURL": "https://your-library.example",
  "allowedHosts": ["your-library.example", "cdn.your-library.example"],
  "entry": {"path": "modules/example-source/index.js", "sha256": "…"}
}

Handlers

Return source-owned identities at every stage.

globalThis.SynthetiqModule = {
  discoveryHome, discoveryFeed,
  searchResults, extractDetails, extractChapters,
  extractImages, extractText, extractResources
};

• DiscoveryBounded rails plus stable, paginated feeds. Never reshuffle an active pagination session.
• SearchPaginated items with stable IDs, titles, links, covers, and truthful hasMore.
• DetailsTitle and identity are required. Reject challenge, login, error, and empty pages.
• ChaptersFollow all source pagination and return the complete section list without UI-sized truncation.
• ImagesHTTPS URLs with any required referer headers, in intentional reading order.
• Text/resourcesBounded text or authorised HTTPS EPUB/PDF resources. DRM and restricted lending are unsupported.

Runtime

Use only the bridges Books provides.

Modules run in an isolated WebKit context. They do not receive filesystem, process, UIKit, contacts, camera, library database, or Keychain access.

Fixtures

Make failures reproducible without copying publications.

Fixtures must be deterministic UTF-8 HTML or JSON using invented/minimal content. Preserve structural fields needed to test parsing, pagination, exclusions, duplicates, and terminal resources. Never commit credentials, private metadata, account cookies, or complete copyrighted chapters.

npm test
node scripts/validate.mjs --skip-hashes
npm run test:module:fixtures -- example-source
npm run test:module:report:fixtures -- example-source

Testing

Use evidence levels that mean what they say.

The canonical public guide contains every command, the report format, failure interpretation, iOS certification boundary, and required handoff.

AI certifier

Let an agent run bounded certification tools.

The repository includes a command-allowlisted local MCP server exposing list_modules, certify_module, certify_flagships, and latest_report. It cannot run arbitrary shell commands or arbitrary paths.

{
  "mcpServers": {
    "synthetiq-books-source-certifier": {
      "command": "node",
      "args": ["/ABSOLUTE/REPOSITORY/PATH/scripts/module-certifier-mcp.mjs"]
    }
  }
}

Updates

Version first, hash last.

1. Keep identity stable. Parser repairs must not silently become a different source family.
2. Bump the semantic version. Existing-version bytes are immutable.
3. Finish JavaScript and icon changes. Avoid regenerating hashes during active editing.
4. Run node scripts/finalize-hashes.mjs. This updates exact repository descriptors.
5. Run npm test. Publish only after deterministic verification succeeds.

Security and policy

A source is executable content with a narrow job.

• Use HTTPS and the smallest observed host allowlist.
• Do not use eval, new Function, downloaded scripts, analytics, telemetry, or browser storage.
• Do not steal credentials, export cookies, bypass CAPTCHA, defeat DRM, or circumvent paywalls.
• Classify content truthfully. Adult-only modules are rejected by Books.
• Use only content and services you are authorised to access.

Troubleshooting

Fix the failing stage, not the symptom.

FAQ

Before you publish.

Does Synthetiq host publications?

No. Books reads files users import and source repositories they choose. A module author remains responsible for its source and use.

Can a fixture pass mark my source ready?

No. It earns FIXTURE_PASS. Live and iOS evidence are separate.

Can I use a ZIP or APK?

No. Books installs loose manifest, JavaScript, and icon files from a repository index.

Can modules expose EPUB or PDF?

Yes, when the publication is openly downloadable or otherwise authorised, uses HTTPS, and is not DRM-protected.

Why does a protected source need iOS testing?

The Node probe cannot reproduce WebKit-owned browser state or pagev2 exactly.