content-core 2.0.7__tar.gz → 2.2.0__tar.gz

{content_core-2.0.7 → content_core-2.2.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "content-core",
-  "version": "2.0.7",
+  "version": "2.2.0",
   "description": "Extract text content from URLs, documents, YouTube videos, Reddit posts, and audio/video files — via CLI (uvx) or MCP.",
   "author": {
     "name": "Luis Novo",

{content_core-2.0.7 → content_core-2.2.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "content-core",
-  "version": "2.0.7",
+  "version": "2.2.0",
   "description": "Extract text content from URLs, documents, YouTube videos, Reddit posts, and audio/video files — via CLI (uvx) or MCP.",
   "skills": "./skills/"
 }

content_core-2.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Keep maintainer configuration out of Git-generated source archives.
+.maintainer/ export-ignore

{content_core-2.0.7 → content_core-2.2.0}/.github/workflows/claude-code-review.yml

@@ -12,11 +12,11 @@ on:
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # Fork PRs get no repository secrets, so the review could only fail there.
+    # (pull_request_target would expose the secrets to untrusted code.)
+    # To also filter by PR author, extend this expression with `&&` -- a job
+    # takes a single `if:`.
+    if: github.event.pull_request.head.repo.full_name == github.repository
 
     runs-on: ubuntu-latest
     permissions:

{content_core-2.0.7 → content_core-2.2.0}/.github/workflows/create-tag.yml

@@ -53,4 +53,5 @@ jobs:
       if: steps.check.outputs.exists == 'false'
       run: |
         echo "✨ Tag v${{ steps.version.outputs.version }} has been created!"
-        echo "🚀 This will trigger the publish workflow automatically."
+        echo "Publish a GitHub Release for this tag to start the PyPI workflow."
+        echo "Creating the tag alone does not publish to PyPI."

{content_core-2.0.7 → content_core-2.2.0}/.github/workflows/package.yml

@@ -2,15 +2,25 @@ name: Package
 
 # Reusable packaging gate: builds the wheel and exercises all three consumer
 # surfaces (library, CLI, MCP server) from the built artifact, with the repo
-# off the path. Called by test.yml (PRs / main) and by publish.yml (tags), so
-# a tag can never publish an artifact that failed this gate.
+# off the path. Called by test.yml (PRs / main) and by publish.yml (published
+# GitHub Releases), so a release cannot upload an artifact that failed this gate.
+#
+# The validated dist/ is uploaded as an artifact so publish.yml can release the
+# exact files this gate checked, instead of rebuilding on another runner.
 on:
   workflow_call:
+    outputs:
+      artifact-name:
+        description: "Name of the uploaded artifact holding the validated dist/"
+        value: ${{ jobs.package.outputs.artifact-name }}
 
 jobs:
   package:
     runs-on: ubuntu-latest
 
+    outputs:
+      artifact-name: ${{ steps.artifact.outputs.name }}
+
     steps:
     - uses: actions/checkout@v4
 
@@ -22,6 +32,12 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v4
 
+    # Unique per run attempt: upload-artifact@v4 rejects a duplicate name within
+    # a run, which would otherwise break "re-run failed jobs".
+    - name: Compute artifact name
+      id: artifact
+      run: echo "name=dist-${{ github.run_id }}-${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"
+
     - name: Build wheel and sdist
       run: |
         rm -rf dist
@@ -90,10 +106,12 @@ jobs:
         uv run --isolated --no-project --with dist/content_core-*.whl \
           python "$RUNNER_TEMP/mcp_smoke.py"
 
-    - name: Wheel version matches pyproject version
+    - name: Wheel version matches project and release tag
+      env:
+        RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
       run: |
         python - <<'PY'
-        import glob, pathlib, re, sys
+        import glob, os, pathlib, re, sys
 
         # tomllib is 3.11+, this job runs on 3.10 - read the [project] version directly.
         text = pathlib.Path("pyproject.toml").read_text()
@@ -115,5 +133,19 @@ jobs:
             sys.exit(f"could not parse version from wheel name {name!r}")
         if match.group(1) != expected:
             sys.exit(f"wheel version {match.group(1)!r} != pyproject version {expected!r}")
+        release_tag = os.environ.get("RELEASE_TAG", "")
+        if release_tag and release_tag not in (expected, f"v{expected}"):
+            sys.exit(f"release tag {release_tag!r} != project version {expected!r}")
         print(f"version match OK: {expected}")
         PY
+
+    # Publish.yml downloads this instead of rebuilding, so the released files
+    # are byte-for-byte the ones validated above. On PR runs it is just an
+    # unused short-lived upload.
+    - name: Upload validated dist
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ steps.artifact.outputs.name }}
+        path: dist/
+        if-no-files-found: error
+        retention-days: 1

content_core-2.2.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  package:
+    uses: ./.github/workflows/package.yml
+
+  # Publishes the exact artifact the packaging gate validated - it is downloaded
+  # from the package job rather than rebuilt here, so a green gate always covers
+  # the files that reach PyPI (uploads are immutable, a rebuild could differ).
+  publish:
+    needs: package
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Download validated dist
+      uses: actions/download-artifact@v4
+      with:
+        name: ${{ needs.package.outputs.artifact-name }}
+        path: dist
+
+    - name: Verify downloaded dist
+      run: |
+        set -euo pipefail
+        ls -la dist/
+        python - <<'PY'
+        import glob, sys
+
+        wheels = glob.glob("dist/content_core-*.whl")
+        sdists = glob.glob("dist/content_core-*.tar.gz")
+        if len(wheels) != 1:
+            sys.exit(f"expected exactly one wheel in dist/, got {wheels}")
+        if len(sdists) != 1:
+            sys.exit(f"expected exactly one sdist in dist/, got {sdists}")
+        print("dist/ OK:", wheels + sdists)
+        PY
+
+    - name: Publish to PyPI
+      env:
+        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      run: uv publish --token "$PYPI_TOKEN"

{content_core-2.0.7 → content_core-2.2.0}/.gitignore

@@ -31,3 +31,7 @@ specs/
 .claude/
 # Intermediate audio extracted from test videos (see processors/media/video.py)
 tests/input_content/*_audio.mp3
+
+# oss-maintainer local state
+.maintainer/profile.local.toml
+.maintainer/state/

content_core-2.2.0/.maintainer/PROFILE.md

@@ -0,0 +1,11 @@
+# Scope and communication
+
+Content Core owns its extraction and summarization API, format processors, engine
+routing, configuration, CLI, MCP server, package metadata and plugin manifests.
+Hosted providers, upstream dependencies and their availability are external.
+
+State observed behavior and validation limits directly. Credit contributors in
+release notes. Do not promise upstream availability or delivery dates.
+
+Do not publish credentials, local configuration, private paths, user input content
+or raw logs containing those values. Publish evidence summaries and public CI links.

content_core-2.2.0/.maintainer/README.md

@@ -0,0 +1,15 @@
+# Maintainer workflows
+
+This directory configures the oss-maintainer release workflow for Content Core.
+It is not a list of maintainers.
+
+- `profile.toml`: commands, required evidence, delivery and publication policy.
+- `PROFILE.md`: scope and public communication conventions.
+- `release/runbook.md`: release preparation, artifact checks and verification.
+- `release/test-matrix.md`: risk-based checks; instantiate on each candidate.
+- `gotchas.md`: verified limitations and lessons.
+- `state/`: ignored run records, logs and artifact identities.
+- `profile.local.toml`: optional ignored preferences; cannot weaken shared gates.
+
+The canonical commands remain in `AGENTS.md`, `Makefile` and the existing GitHub
+workflows. This profile configures releases only; other capabilities are not onboarded.

content_core-2.2.0/.maintainer/gotchas.md

@@ -0,0 +1,31 @@
+# Release gotchas
+
+- `make release` publishes the existing draft GitHub Release and starts PyPI
+  distribution through `release: published`. It requires the exact candidate GO.
+  `make tag` only creates/pushes the version tag under the current workflow; saving
+  a draft release does not distribute to PyPI. Tags pointing to old workflow
+  revisions can still carry the former tag-push trigger; do not use them for a cut.
+- The GitHub Release must reference the validated candidate. Verify the remote
+  tag's resolved commit before publication. The Package job rejects a release tag
+  that differs from the project version (with or without the `v` prefix).
+- `published` covers releases published directly or from drafts, including
+  prereleases. Editing an already published release does not trigger a new upload.
+- `Publish` builds again in its reusable Package job, then uploads those validated
+  bytes to PyPI without rebuilding in the publish job. Pre-GO and release-run builds
+  are separate artifacts; compare hashes and verify the actual registry files.
+- `uv build` alone is not the package gate. Exercise the installed library, CLI
+  and real MCP initialization response outside the checkout.
+- `uv run --isolated --no-project` does not itself isolate Python imports. Use
+  a temporary working directory, absolute wheel/fixture paths and `python -I`.
+- `make ruff` modifies files. Lint and mypy are not release gates (`AGENTS.md`).
+- E2E suites may call paid services or download large models. Select and authorize
+  their scope before execution; skips and missing credentials are not passes.
+- The default `python3` on the current maintainer machine is older than the plugin
+  scripts require. Use an available Python >=3.11 for profile/run-record scripts;
+  this does not change the package's Python >=3.10 compatibility requirement.
+- On 2026-09-05 the Dependabot API returned HTTP 403 with alerts disabled. Security
+  alerts were unverified, not absent. Recheck on each release.
+- `released` is not currently a repository label. Creating it or applying release
+  labels requires the owner's agreement; do not create labels during bootstrap.
+- `.gitattributes` export-ignore affects Git archives, not necessarily Hatch's
+  sdist selection. Inspect the built sdist for accidental local-state inclusion.

content_core-2.2.0/.maintainer/profile.toml

@@ -0,0 +1,51 @@
+schema_version = 1
+
+[project]
+name = "Content Core"
+repo = "lfnovo/content-core"
+artifact = "pypi-library"
+commands_doc = "AGENTS.md"
+
+[commands.validator]
+run = "make test"
+cwd = "."
+timeout = "15m"
+
+[contributing]
+conventions = "CONTRIBUTING.md"
+
+[release]
+process_doc = ".maintainer/release/runbook.md"
+change_delivery = "pr"
+versioning = "repository"
+changelog = "CHANGELOG.md"
+version_files = ["pyproject.toml", ".claude-plugin/plugin.json", ".codex-plugin/plugin.json", "uv.lock"]
+lock_command = "uv sync"
+distribution_trigger = "make release"
+publish_workflow = ".github/workflows/publish.yml"
+notes_source = "CHANGELOG.md"
+consumer_surfaces = ["public Python API", "CLI commands and flags", "MCP tools and parameters", "configuration keys and environment variables", "supported formats and engines"]
+
+[release.gates]
+mandatory = ["validator", "package-gate", "bucket-c", "notes-approved"]
+optional = ["security-alerts"]
+not_gates = ["ruff", "mypy", "test-e2e", "test-e2e-heavy"]
+merge_own_prs = "ask-once-per-session"
+alerts_policy = "Report alerts when accessible. Disabled or inaccessible alerts remain not-run; never report zero alerts from an API error. Report known unresolved vulnerabilities to the owner before GO."
+
+[artifacts.pypi]
+package = "content-core"
+# Existing build entry point. package-gate passes only after ALL the runbook's
+# artifact-gate steps, including clean-room smokes and extras installation.
+gate = "uv build"
+surfaces = ["library", "cli", "mcp"]
+extras = ["docling", "crawl4ai", "langchain"]
+identity = "sha256"
+
+[comms]
+owner_language = "pt-BR"
+public_language = "en"
+agent_attribution = "none"
+
+[channels]
+announce = []

content_core-2.2.0/.maintainer/release/runbook.md

@@ -0,0 +1,128 @@
+# Release runbook
+
+## Agreement and versioning
+
+Follow `CONTRIBUTING.md` for PR delivery, `AGENTS.md` for canonical validation,
+`ARCHITECTURE.md` for compatibility decisions and `CHANGELOG.md` for SemVer.
+The existing architecture decision treats fixes to hidden extraction errors as
+2.x fixes. New supported formats and public API additions are minor changes;
+breaking supported consumer contracts require explicit version review. The owner
+decides the release number. Artifact: pypi-library; distribution trigger: `make release`,
+which publishes the reviewed draft GitHub Release (`release: published`).
+
+Prepare changes in a branch and PR. Required branch protections and review remain
+binding. Ask once per session before merging qualifying own PRs. A merge to main
+runs tests but does not publish. Creating/pushing a tag or saving a draft release
+does not publish to PyPI when the tag contains the current workflow. Only the exact
+final candidate GO permits `make release`.
+
+## Scope and source validation
+
+Fetch tags after bootstrap. Compare the latest release with the candidate; audit
+all behavior changes and their issue/PR references against the changelog. Record
+the candidate SHA, pre-existing working-tree changes and chosen checks under
+`.maintainer/state/`. Keep user files, including untracked files, intact.
+
+Run `make test` from the candidate checkout and retain the log/exit status.
+Require successful Test workflow jobs for Python 3.10, 3.11 and 3.12, plus Package,
+on the final integrated candidate. `AGENTS.md` explicitly excludes ruff, mypy and
+broad external-service E2E suites from validator gates. The selected plan defines
+any optional external checks and authorized costs before those checks run.
+
+## Artifact gate
+
+The canonical builder is `uv build`; the canonical smoke implementations are
+in `.github/workflows/package.yml`. A successful build alone is insufficient.
+
+1. Use a fresh candidate checkout or an empty release-owned `dist/`; run `uv build`.
+2. Require exactly one wheel and one sdist. Compare their version with
+   `pyproject.toml`, both plugin manifests and the content-core entry in `uv.lock`.
+3. Run the workflow's runtime-assets inspection against this wheel. Inspect the
+   sdist too; exclude local state, credentials and accidental development artifacts.
+4. Resolve the wheel and fixture paths to absolute paths. In a fresh temporary
+   working directory, use the workflow's `uv run --isolated --no-project --with`
+   commands against that wheel; use `python -I` for Python probes. Prove the module
+   origin is an installed environment, not this checkout. Import `content_core`,
+   its public API and public exception exports. Call `extract_content` on the
+   existing `tests/input_content/file.txt` fixture and assert non-empty content.
+5. Exercise `content-core --help`, `content-core --version`, and the workflow's
+   real TXT and PDF extraction commands using absolute fixture paths. Check that
+   the JSON result contains expected extracted content.
+6. Run the workflow's real stdio `initialize` handshake with `content-core-mcp`
+   from the isolated directory. Require a JSON-RPC result without an error and
+   `serverInfo.version` equal to the candidate version. Retain stdout/stderr.
+7. Install each declared extra (`docling`, `crawl4ai`, `langchain`) with the exact
+   wheel in an isolated environment and check the dependency installation succeeds.
+   Installation is not evidence of successful live provider calls or model runs.
+8. Record SHA-256 for both artifacts and link every result to the tested bytes.
+   Retain artifacts until post-publication verification finishes.
+
+The release agent adapts the existing workflow commands to absolute paths in the
+execution plan, before running them. It must not substitute editable/source tests
+for these checks. Re-run affected checks after fixes and the full final artifact
+gate after the version cut is integrated.
+
+## Manual scope
+
+The matrix distinguishes automated regression coverage from optional live checks.
+The owner reviews results and explicit unverified paths; that acknowledgment is
+`bucket-c`. If a manual check is made mandatory for the candidate, it must actually
+pass. Missing credentials remain unverified and never receive an inferred pass.
+Neither this profile nor its approval authorizes paid calls or large model runs.
+
+## Cut and notes
+
+Bump `pyproject.toml`, `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`
+together, then use the existing `uv sync` command to update `uv.lock`. Confirm only
+intended lock changes and verify all package-version values agree. Leave the
+marketplace's independent schema/catalog version unchanged.
+
+Date the versioned changelog in the owner's timezone and open a fresh Unreleased
+section. Commit all cut files together through the PR process. Collect contributor
+credits and approve the exact notes before publication.
+
+After the final candidate is integrated and validated, prepare its tag with
+`make tag` from that exact commit. Verify the remote tag resolves to the candidate.
+Create a draft with `gh release create <tag> --verify-tag --draft --title <version>
+--notes-file .maintainer/state/release-notes.md`. A draft is preparation, not GO.
+Do not use a tag from an older commit whose workflow still publishes on tag push.
+
+## Publish — only after GO
+
+Present all mandatory results, manual acknowledgment, security visibility, exact
+candidate SHA, wheel/sdist SHA-256, approved notes and `make release`. Immediately
+before the trigger, recheck HEAD, version files, the remote tag's resolved commit,
+and the draft release's tag, notes and draft status. Confirm the version is still
+absent from PyPI.
+
+Run `make release` once on the approved candidate. It uses
+`gh release edit <tag> --draft=false --latest`; publishing the draft emits
+`release: published` and starts `.github/workflows/publish.yml`. Publishing a
+release directly in GitHub is the same distribution action and requires the same
+GO. Draft creation, tag pushes and edits to an already published release do not
+start this workflow. The published event includes prereleases; their tag must
+match the project's version (optionally prefixed with `v`).
+
+Observe Publish to completion. Its Package job checks out the release tag, builds
+and validates the artifacts, and checks the tag against the package version before
+upload. A failure requires an owner decision; do not delete/recreate the release,
+retry through another path or overwrite a version to work around it. Verify the
+published release page still contains the approved notes.
+
+## Post-publication verification
+
+Download both published files from PyPI for the exact version and record their
+SHA-256 separately from tested hashes. Compare them with the pre-GO artifacts and
+the release-run Package artifact. The release workflow builds afresh, so report differences
+and repeat the artifact smokes on the actual published wheel. Install the exact
+version from PyPI in a fresh environment outside the checkout and repeat library,
+CLI and MCP probes. Check the release page's tag, approved notes and latest status.
+
+## Cleanup and closure
+
+Record announcement disposition (none configured; the owner posts any later
+approved text). Do not create/apply release labels without agreement.
+Stop only processes started by this run and remove only its temporary environments,
+fixtures and artifacts after retaining required evidence. Check the working tree
+against its initial state. Record publish, verify, announcement disposition and
+cleanup before closing the run with GO. Retro work is independent of delivery.

content_core-2.2.0/.maintainer/release/test-matrix.md

@@ -0,0 +1,23 @@
+# Release test matrix
+
+Instantiate against the final candidate before execution. For 2.1.0, compare v2.0.7 with the final candidate: HTML ingestion, engine/configuration
+errors, public exceptions, logging, MCP version, packaging and release publication.
+Record the concrete SHA and artifact hashes in the run record.
+
+| Bucket / risk | Command or concrete action | Expected evidence | Resources / authority | Timing / disposition |
+|---|---|---|---|---|
+| A: shared routing/configuration, exception, HTML, logging and MCP regressions | `make test` | No unit/integration failures; log and candidate SHA | Local fixtures, no API calls | Pre-GO, mandatory validator |
+| A: Python compatibility | Existing Test workflow on final candidate, Python 3.10/3.11/3.12 | All three jobs passed with matching SHA | GitHub CI | Pre-GO, required project checks |
+| A: wheel/sdist and consumer surfaces | `uv build`, then every Artifact gate step in runbook; existing Package workflow | Installed library call, CLI TXT/PDF extraction, real MCP response, assets/version agreement and both SHA-256 values | Isolated environments; package downloads; no paid API calls | Pre-GO, mandatory package-gate |
+| A: optional dependency installation | Install exact wheel with each of docling/crawl4ai/langchain, as runbook specifies | All extras install; do not claim live engine coverage | Package downloads, potentially large ML dependencies; no model inference | Pre-GO, part of package-gate |
+| A: release trigger and version identity | Validate workflow syntax; exercise Package version check with matching/mismatched release tags and wheel versions; dry-run Make targets | Only `release: published` triggers Publish; draft/tag preparation does not upload; mismatched versions fail; Package artifacts feed upload | Local workflow checks, no publication | Pre-GO, required for workflow changes |
+| C: owner review of evidence and gaps | Review results and named unverified provider paths; approve exact notes including credits | Owner acknowledgment and exact approved text | Owner | Pre-GO, bucket-c and notes-approved |
+| C: optional live URL routing | After scoped approval: `uv run pytest tests/e2e/test_url_engines.py -v -m e2e` | Per-test results; skips explicitly unverified | Network; Firecrawl credentials/usage, Jina and Crawl4AI environment; execution/count/cost requires separate agreement | Pre-GO signal; not a mandatory broad E2E gate |
+| C: optional real Docling baseline | After scoped approval: `uv run pytest tests/e2e/test_docling.py::test_docling_pdf_extraction -v -m e2e_heavy` | Non-empty PDF extraction via explicit Docling | Large model downloads and local compute; separate scope approval | Pre-GO signal; unrun means unverified |
+| C: unchanged media/network baselines | Select existing node IDs from tests/e2e/test_media.py, test_youtube.py and test_remote.py after credential/cost review | Per-test observed outcomes | Network; STT provider may incur cost | Optional; unrun means unverified |
+| Signal: security alerts | Read repository Dependabot alerts; report unavailable API separately | Alert details or explicit not-run reason | Read-only GitHub access | Pre-GO, optional signal requiring honest disclosure |
+| A: registry delivery | Download exact PyPI version, compare hashes and repeat isolated library/CLI/MCP smokes | Actual published digests, working surfaces, correct release page | Network, fresh environment | Post-publication, required delivery verification |
+
+Bucket B: no new automation project is selected. Existing unit/integration and CI
+packaging checks cover the deterministic changes. Any investment proposal is a
+separate owner decision. This plan does not authorize paid/live suite execution.

content_core-2.0.7/CLAUDE.md → content_core-2.2.0/AGENTS.md

@@ -37,7 +37,7 @@ uv sync --group dev
 uv run pytest tests/unit tests/integration -v
 ```
 
-This is the gate. It returns clean pass/fail in ~15s, requires no credentials or network, and matches what CI enforces on `main` (CI runs only `tests/unit`; integration tests are also safe locally — no network/API keys). For targeted feedback during iteration, use `uv run pytest -k "<keyword>"` per the table in the Testing section below.
+This is the gate. It returns clean pass/fail in ~15s and requires no credentials or network. CI on PRs and `main` runs exactly these tests (`tests/unit tests/integration`) across Python 3.10/3.11/3.12, plus a packaging gate (`.github/workflows/package.yml`) that builds the wheel and exercises the library, the `content-core` CLI and the `content-core-mcp` server from the built artifact. The packaging gate needs no credentials either, but it is not reproducible from a plain pytest run — if you touch packaging metadata (`pyproject.toml`, entry points, package data), expect it to be the check that catches you. For targeted feedback during iteration, use `uv run pytest -k "<keyword>"` per the table in the Testing section below.
 
 ### Do NOT use as gates
 
@@ -51,7 +51,7 @@ If you believe a task genuinely requires lint or type cleanup, do it as a *separ
 
 - Single processor changes (`processors/url/*.py`, `processors/document/*.py`, `processors/media/*.py`) are the natural unit of work — keep changes confined to one file plus its matching test in `tests/unit/`.
 - Avoid touching `extraction.py` (orchestrator) or `config.py` unless the task explicitly targets routing or configuration.
-- New processors should follow the `Processor` protocol in `src/content_core/processors/protocol.py`.
+- New processors follow the function contract documented in `ARCHITECTURE.md` ("Two-layer contract"): a module-level `async def extract_<fmt>_file(file_path, config) -> ExtractionOutput` that raises on failure, with per-unit degradation in the inner parsing layer.
 
 ## Codebase Structure
 
@@ -76,8 +76,7 @@ src/content_core/
 │   └── identification/      # File type detection (pure Python)
 │
 ├── processors/
-│   ├── protocol.py          # Processor Protocol definition
-│   ├── text.py              # Plain text + HTML-to-markdown
+│   ├── text.py              # Plain text + HTML-to-markdown (also .html/.htm files, <title> extraction)
 │   ├── url/                 # URL extraction engines
 │   │   ├── __init__.py      # Engine router + fallback chain
 │   │   ├── bs4.py           # BeautifulSoup + readability
@@ -93,6 +92,7 @@ src/content_core/
 │   │   ├── docx.py          # python-docx
 │   │   ├── pptx.py          # python-pptx
 │   │   ├── xlsx.py          # openpyxl
+│   │   ├── odf.py           # ODT/ODS/ODP via odfpy
 │   │   └── docling.py       # Optional Docling integration
 │   └── media/               # Audio/video processing
 │       ├── __init__.py      # Video→audio pipeline
@@ -130,7 +130,7 @@ from content_core import ContentCoreConfig
 config = ContentCoreConfig(url_engine="firecrawl", audio_concurrency=5)
 ```
 
-Key settings: `url_engine`, `document_engine`, `audio_provider`, `audio_model`, `firecrawl_api_url`, `youtube_languages`, `llm_provider`, `llm_model`, `docling_ocr`, `docling_formulas`, `docling_vision`
+Key settings: `url_engine`, `document_engine`, `audio_provider`, `audio_model`, `firecrawl_api_url`, `youtube_languages`, `youtube_cookies_file`, `youtube_proxy`, `llm_provider`, `llm_model`, `docling_ocr`, `docling_formulas`, `docling_vision`
 
 Docling enrichment flags (`docling_ocr`, `docling_formulas`, `docling_vision`) control OCR, formula extraction, and image/chart processing when `document_engine="docling"`. These are also exposed as CLI flags (`--formulas`, `--pictures`, `--no-ocr`) and MCP parameters.
 
@@ -167,14 +167,15 @@ When you change a specific processor or module, run only the relevant tests for
 | `processors/url/youtube.py` | `uv run pytest -k "youtube"` |
 | `processors/url/reddit.py` | `uv run pytest -k "reddit"` |
 | `processors/document/pdf.py` | `uv run pytest -k "pdf"` |
-| `processors/document/docx.py` or `pptx.py` or `xlsx.py` | `uv run pytest -k "office"` |
+| `processors/document/docx.py` or `pptx.py` or `xlsx.py` or `odf.py` | `uv run pytest -k "office"` |
 | `processors/document/docling.py` | `uv run pytest -k "docling"` |
-| `processors/text.py` | `uv run pytest -k "text_processing"` |
+| `processors/text.py` | `uv run pytest -k "text_processing or html_file"` |
 | `processors/media/audio.py` | `uv run pytest -k "audio or media_pipeline"` |
 | `processors/media/video.py` | `uv run pytest -k "media_pipeline"` |
 | `mcp/server.py` | `uv run pytest -k "mcp"` |
 | `cli.py` | `uv run pytest -k "cli"` |
 | `common/retry.py` | `uv run pytest -k "retry"` |
+| `common/exceptions.py` | `uv run pytest -k "exceptions"` |
 | `content/identification/` | `uv run pytest -k "file_detector"` |
 | `common/state.py` (models) | `uv run pytest -k "models"` |
 
@@ -191,20 +192,22 @@ tests/
 │   ├── test_pdf_extraction.py     # PDF text cleaning, extraction with mocked pdfplumber
 │   ├── test_pdf_helpers.py        # Formula detection, table conversion helpers
 │   ├── test_epub_extraction.py    # EPUB extraction with mocked fast-ebook
-│   ├── test_office_extraction.py  # DOCX/PPTX/XLSX routing and extraction
+│   ├── test_office_extraction.py  # DOCX/PPTX/XLSX/ODT/ODS/ODP routing and extraction
 │   ├── test_docling_extraction.py # Docling output formats with mocked converter
-│   ├── test_text_processing.py    # HTML detection, markdown conversion
+│   ├── test_text_processing.py    # HTML detection, markdown conversion, <title>/<head> handling
+│   ├── test_html_file_extraction.py # Local .html file → markdown via text processor
 │   ├── test_media_pipeline.py     # Audio transcription, video pipeline, stream selection
 │   ├── test_audio_concurrency.py  # Semaphore, ordering, concurrency limits
 │   ├── test_mcp_v2.py             # MCP tools: extract + summarize
 │   ├── test_cli.py                # CLI: _build_input, commands, config subcommands
 │   ├── test_config_file.py        # TOML config file: read/write, set/delete, precedence
-│   ├── test_models_v2.py          # ExtractionInput/Output, Processor Protocol
+│   ├── test_models_v2.py          # ExtractionInput/Output data models
 │   ├── test_retry.py              # Retry decorators, exception classification
+│   ├── test_exceptions.py         # Exception taxonomy + public exports
 │   └── test_file_detector*.py     # MIME detection, performance, edge cases
 │
 ├── integration/       # Local files, no network (~22 tests)
-│   ├── test_extraction.py   # Real file extraction (PDF, DOCX, PPTX, XLSX, EPUB, etc.)
+│   ├── test_extraction.py   # Real file extraction (PDF, DOCX, PPTX, XLSX, ODT/ODS/ODP, EPUB, HTML, etc.)
 │   └── test_cli_v2.py       # CLI subcommands via CliRunner with real extraction
 │
 └── e2e/
@@ -214,3 +217,10 @@ tests/
     ├── [e2e] test_media.py         # Audio/video transcription via STT API
     └── [e2e_heavy] test_docling.py # Docling extraction with enrichment flags
 ```
+
+## Maintainer workflows
+
+Maintainer profile lives in `.maintainer/`; do not run release, triage or discussions workflows without it.
+PyPI publication is triggered by a published GitHub Release (`release: published`).
+`make tag` prepares the tag; `make release` publishes its reviewed draft release.
+Follow `.maintainer/release/runbook.md` for candidate validation and publication.

{content_core-2.0.7 → content_core-2.2.0}/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-03
+
+### Added
+- OpenDocument extraction for `.odt`, `.ods` and `.odp` through the office route, using `odfpy` (new core dependency). Text documents become markdown paragraphs, headings, lists and tables; spreadsheets become one markdown table per sheet; presentations become one block per slide. Detection reads the ZIP's `mimetype` member, so a wrong or missing extension still works (#43).
+- YouTube cookie and proxy support for the transcript path (#46). `youtube_cookies_file` (`CCORE_YOUTUBE_COOKIES_FILE`) loads a Netscape `cookies.txt` into the `youtube-transcript-api` session, unblocking IP-flagged networks; a missing or unreadable file raises `ConfigurationError`. `youtube_proxy` (`CCORE_YOUTUBE_PROXY`) routes both `youtube-transcript-api` and the `pytubefix` fallback through a proxy URL — use a residential proxy, as datacenter proxies are blocked. With neither set, behavior is unchanged. Cookie values are never logged.
+- `audio_segment_minutes` setting (`CCORE_AUDIO_SEGMENT_MINUTES`) controls the length of the segments long audio is split into before transcription. The default stays 10 minutes; `0` sends the file whole, for self-hosted STT endpoints without an upload size limit (#94).
+
+### Changed
+- **URL extraction failures now raise instead of returning empty output** (#60). `content=""` now only means the source was genuinely empty. A named `url_engine` that fails raises `NetworkError` (connection/timeout/DNS), `NotFoundError` (HTTP 404/410 from the page, `simple` engine), `ExternalServiceError` (engine API or HTTP errors) or `ConfigurationError` (`crawl4ai` not installed). `auto` still falls through firecrawl → jina → crawl4ai → simple and raises the last error only when every engine failed. A malformed URL raises `InvalidInputError`. The `simple` engine no longer returns `"Failed to extract content: ..."` or `"No content found"` as page content. Remote-file downloads raise the same typed errors, and a download that cannot be saved locally raises `FileOperationError`.
+- File extraction failures raise typed errors (#60): corrupted PDF, EPUB or unreadable text files raise `FileOperationError` (chained to the original cause) instead of bare `Exception`/`RuntimeError`; a missing file still raises `FileNotFoundError`. ffmpeg/ffprobe failures in audio and video processing raise `FileOperationError`: video extraction no longer returns empty content when ffprobe or ffmpeg fails. Speech-to-text provider failures (after retries) raise `ExternalServiceError`, and an STT model that cannot be created raises `ConfigurationError`.
+- Retry classification now treats `ConfigurationError`, `UnsupportedTypeException`, `InvalidInputError` and `FileOperationError` as permanent and `NetworkError` as transient (#60).
+- YouTube extraction raises instead of returning empty content when no transcript can be fetched (#60): `NoTranscriptFound` when neither youtube-transcript-api nor pytubefix finds a transcript, `ExternalServiceError` (chained to the provider error) when YouTube blocks or fails the request on both paths, e.g. `IpBlocked`, and `InvalidInputError` for a YouTube URL without a video ID. Provider errors from `get_best_transcript` and `extract_transcript_pytubefix` now propagate after retries instead of being swallowed (`extract_transcript_pytubefix` still returns `(None, None)` for a video without captions); a failure of the first path still falls back to the second.
+- An explicit `audio_provider`/`audio_model` that cannot be created now raises `ConfigurationError` instead of silently transcribing with the default STT model, per "Explicit choice is a requirement" (#99).
+- youtube-transcript-api failures are retried by type: blocked requests (`RequestBlocked`/`IpBlocked`) are retried, so a rotating proxy can get a new IP; other transcript errors that name a state of the video (unavailable, transcripts disabled, age-restricted...) are not (#99).
+
+### Fixed
+- `youtube_proxy` now also applies to the YouTube video title lookup, which previously used only env-var proxies (#99).
+- `requests`, imported directly for the YouTube cookie session, is declared as a dependency instead of arriving transitively (#99).
+- A failed Crawl4AI crawl (navigation timeout, blocked page) now raises `ExternalServiceError` instead of failing with a pydantic `ValidationError` on `content=None`, and `auto` falls through to the next engine. Applies to both the local browser and the Docker API mode (#101).
+
+### Security
+- Raised minimum versions to releases without known vulnerabilities: `aiohttp>=3.14.3`, `pillow>=12.3.0`, `click>=8.3.3`, `pydantic-settings>=2.14.2`, and in the extras `docling>=2.94.0`, `crawl4ai>=0.9.0` and `langchain-core>=1.3.3`. Upgrading content-core upgrades these packages in an existing environment. The development lock was refreshed; it now also exercises `fastmcp` 4 and `mcp` 2, which fresh installs already resolve to (#102).
+
+## [2.1.0] - 2026-09-06
+
+### Added
+- Local HTML file ingestion through the simple engine, including `.html`/`.htm` routing, HTML-to-Markdown conversion, document titles, minimal HTML documents, BOMs and legacy character encodings (#59, #66).
+- Public exception exports from `content_core`: `ContentCoreError`, `UnsupportedTypeException`, `InvalidInputError`, `ConfigurationError`, `NotFoundError`, `NoTranscriptFound`, `NetworkError`, `ExternalServiceError` and `FileOperationError` (#50, #52). Typed failures can be caught through the public API. Some existing failures still escape as untyped exceptions until #60; exporting the taxonomy does not complete that migration.
+
+### Changed
+- PyPI publication starts when a GitHub Release is published, including publishing a draft. Creating or pushing a tag alone no longer publishes. The packaging gate verifies that the release tag matches the package version (#93).
+- Library imports no longer configure process-wide Loguru handlers. Content Core logging is disabled by default for library consumers; use `logger.enable("content_core")` with the host application's handlers, or `content_core.configure_logging()` from an application entry point. CLI and MCP entry points configure their own stderr logging and honor debug settings (#47).
+- Published wheel and sdist now come directly from the artifacts validated by the publishing workflow's packaging job, rather than being rebuilt in the upload job (#57).
+
+### Removed
+- Unused `asciidoc` dependency (#58).
+- Unused internal `Processor` Protocol; processor contracts remain documented in `ARCHITECTURE.md` (#53).
+- Unused internal exception classes `DatabaseOperationError`, `AuthenticationError` and `RateLimitError` (#52). None had a raise site; direct imports from `content_core.common.exceptions` must be updated. The replacement taxonomy is public, but provider error wrapping is still incomplete pending #60.
+
+### Fixed
+- Explicit `document_engine="docling"` now raises `ConfigurationError` when the optional engine is unavailable, instead of silently using the simple engine. The error names `pip install "content-core[docling]"` and the `CCORE_DOCUMENT_ENGINE=simple` alternative. `auto` still permits fallback, and `check_file_support` returns an unsupported verdict with the reason (#50).
+- Invalid engine names are rejected at configuration entry points, including constructor arguments, environment variables, TOML files and `content-core config set`. Misspelled boolean values are also rejected before writing; CLI/MCP validate engine names for the input type (#51).
+- MCP `serverInfo.version` reports the installed Content Core version instead of FastMCP's version (#56).
+
+### Documentation
+- Documented Firecrawl-compatible backends through `FIRECRAWL_API_URL` (#86).
+
 ## [2.0.7] - 2026-09-02
 
 ### Added

content_core-2.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md