feat: polish OSS release experience

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: Bug report
+description: Report a reproducible DocTruth bug
+title: "fix: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please use synthetic documents and remove secrets, API keys, and customer data.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong?
+      placeholder: DocTruth returned a weak citation for an exact source quote.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Minimal steps, code, document shape, or fixture needed to reproduce.
+      placeholder: |
+        1. Parse sample.pdf with PdfDocumentParser
+        2. Extract Contract.class with withProvenance()
+        3. Observe citation matchScore...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - PDF parser
+        - DOCX parser
+        - XLSX parser
+        - CSV parser
+        - Citation matching
+        - Bounding boxes
+        - JSON Schema
+        - Java schema reflection
+        - Provider integration
+        - Audit JSON
+        - CLI
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      placeholder: 0.2.0-alpha or commit SHA
+    validations:
+      required: true
+  - type: input
+    id: java
+    attributes:
+      label: Java version
+      placeholder: java -version
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or audit output
+      description: Paste minimal logs or audit JSON. Redact secrets and source documents.
+      render: text

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: mailto:security@doctruth.ai
+    about: Please report security issues privately instead of opening a public issue.
+  - name: Sensitive document or data issue
+    url: mailto:security@doctruth.ai
+    about: Do not attach real customer documents, secrets, or regulated data to public issues.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Propose a narrowly-scoped DocTruth capability
+title: "feat: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        DocTruth accepts features that strengthen source evidence, provenance, confidence, schema validation, or audit export. General agent, RAG, UI, or workflow features are usually out of scope.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What evidence, extraction, validation, or audit problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the smallest useful API or behavior change.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Parser evidence
+        - Citation matching
+        - Bounding boxes
+        - Schema validation
+        - Provider behavior
+        - Audit JSON
+        - CLI
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What did you try instead?
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This feature needs source evidence, provenance, confidence, schema validation, or audit export semantics.
+          required: true
+        - label: This feature is not a general-purpose agent, vector store, chatbot, or UI workflow request.
+          required: true

.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: maven
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: Australia/Sydney
+    open-pull-requests-limit: 5
+    groups:
+      maven-runtime:
+        dependency-type: production
+      maven-test:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:30"
+      timezone: Australia/Sydney
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Scope
+
+<!-- Public API, parser, citation, provider, audit JSON, docs, tests, or release? -->
+
+## Verification
+
+- [ ] `mvn test`
+- [ ] `mvn verify`
+- [ ] `mvn spotless:check`
+- [ ] `mvn checkstyle:check`
+- [ ] Documentation updated, if behavior changed
+
+## Contract Checklist
+
+- [ ] Public API changes are intentional and called out
+- [ ] Source evidence, provenance, confidence, or audit semantics are preserved
+- [ ] No new direct dependency without an ADR
+- [ ] No real customer documents, secrets, API keys, or personal data included
+- [ ] New behavior has a focused test at the closest contract boundary
+
+## Notes For Reviewers
+
+<!-- Anything risky, intentionally deferred, or worth special attention? -->

.github/workflows/ci.yml

@@ -38,6 +38,21 @@ jobs:
       - name: Verify (unit + integration + recorded LLM + coverage)
         run: mvn -B -ntp verify -P recorded
 
+      - name: Resolve project version
+        run: echo "PROJECT_VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)" >> "$GITHUB_ENV"
+
+      - name: Compile quickstart against packaged SDK
+        run: scripts/compile-quickstart.sh
+
+      - name: Package CLI release artifacts
+        run: scripts/package-cli-release.sh --version "${PROJECT_VERSION}"
+
+      - name: Smoke CLI release tarball
+        run: scripts/smoke-cli-release.sh --version "${PROJECT_VERSION}"
+
+      - name: Generate SBOM
+        run: mvn -B -ntp -DskipTests cyclonedx:makeAggregateBom
+
       - name: Upload surefire reports on failure
         if: failure()
         uses: actions/upload-artifact@v4

.github/workflows/dependency-review.yml

@@ -0,0 +1,20 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  review:
+    name: dependency vulnerability scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: always

.github/workflows/javadocs.yml

@@ -0,0 +1,46 @@
+name: Javadocs
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: publish javadocs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+          cache: maven
+
+      - name: Generate Javadocs
+        run: mvn -B -ntp javadoc:javadoc
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: target/site/apidocs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/nightly-live.yml

@@ -0,0 +1,46 @@
+name: Nightly Live LLM
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 17 * * *'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: nightly-live-llm
+  cancel-in-progress: false
+
+jobs:
+  live-smoke:
+    name: live provider contract smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+          cache: maven
+
+      - name: Run bounded live LLM smoke
+        run: mvn -B -ntp -P live -Dit.test=ExternalLlmSmokeIT failsafe:integration-test failsafe:verify
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+
+      - name: Upload live smoke reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: nightly-live-failsafe
+          path: '**/target/failsafe-reports'
+          retention-days: 14