chore: prepare repo for public release

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Something in xrag behaves incorrectly
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. Please redact all API keys and any
+        confidential document content before submitting.
+
+        For security vulnerabilities, follow
+        [SECURITY.md](https://github.com/henryle97/xrag/blob/main/SECURITY.md)
+        instead of opening a public issue.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you observe, and what did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: >
+        A minimal snippet or CLI invocation. Include the relevant config with
+        credentials redacted.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: xrag version
+      description: "Output of `python -c \"import xrag; print(xrag.__version__)\"`"
+      placeholder: "0.5.3"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12.9"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which area?
+      options:
+        - parser
+        - chunker
+        - enrichment
+        - embedding
+        - indexing / vector store
+        - retrieval / rerank
+        - generation
+        - Xrag client
+        - CLI
+        - eval / benchmark
+        - packaging / install
+        - not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or traceback
+      description: Paste the full traceback if there is one. Redact credentials.
+      render: shell
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else?
+      description: >
+        Vector store backend, provider models, document type, or anything else
+        that helps reproduce.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or usage help
+    url: https://github.com/henryle97/xrag/discussions
+    about: Ask how to use xrag, or discuss an idea before filing a feature request.
+  - name: Security vulnerability
+    url: https://github.com/henryle97/xrag/security/advisories/new
+    about: Report privately. Please do not open a public issue for security problems.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Suggest a capability or improvement for xrag
+labels: ["needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: >
+        Describe the use case rather than a specific implementation. What are
+        you unable to do today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would the API, config, or CLI surface look like?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Workarounds you tried, or other designs you weighed.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which area?
+      options:
+        - parser
+        - chunker
+        - enrichment
+        - embedding
+        - indexing / vector store
+        - retrieval / rerank
+        - generation
+        - Xrag client
+        - CLI
+        - eval / benchmark
+        - packaging / install
+        - not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd be willing to open a PR for this

.github/dependabot.yml

@@ -0,0 +1,36 @@
+version: 2
+updates:
+  # Keep CI actions current — these are the highest-value updates for a
+  # library, since a compromised action runs with repo credentials.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["needs-triage"]
+    commit-message:
+      prefix: "ci"
+
+  # Python dependencies. Grouped so routine patch bumps arrive as one PR
+  # rather than flooding the queue.
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: ["needs-triage"]
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      patch-and-minor:
+        update-types:
+          - minor
+          - patch
+    ignore:
+      # LangChain majors are pinned deliberately and exercised by the contract
+      # matrix in ci.yml. Bump these by hand alongside that matrix.
+      - dependency-name: "langchain"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "langchain-core"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "langchain-openai"
+        update-types: ["version-update:semver-major"]

.github/pull_request_template.md

@@ -1,5 +1,5 @@
 <!--
-xrag PR template. See docs/contributing.md §3 for the conventions
+xrag PR template. See CONTRIBUTING.md §3 for the conventions
 this template encodes. Keep the four-bullet Summary shape; skip the
 Risks section entirely when there are none rather than writing "None".
 -->
@@ -24,7 +24,7 @@ ONE `Closes #N` per issue, each on its own content line.
 GitHub's auto-close parser only fires on `Closes`/`Fixes`/`Resolves`
 when the keyword is on the same content line as the reference — a
 heading like `## Closes` followed by `#19, #20, #21` will silently
-fail to close anything. See docs/contributing.md §3.1.
+fail to close anything. See CONTRIBUTING.md §3.1.
 
 Single-issue example:
   Closes #42

.gitleaksignore

@@ -0,0 +1,17 @@
+# Reviewed gitleaks false positives.
+#
+# Fingerprints are <path>:<rule>:<line> and are line-sensitive: if one of
+# these lines moves, gitleaks re-reports it and the fingerprint below needs
+# updating. Re-verify that the match is still a placeholder before doing so —
+# never add a fingerprint without reading the line it points at.
+
+# `dedup_family=True` is a retrieval config flag. The generic-api-key rule
+# matches the `<word>=<value>` shape, not anything secret. This entry is a
+# table of doc snippets asserted to stay in sync with the default config.
+tests/unit/test_client_app_config.py:generic-api-key:94
+
+# `Authorization: Bearer rk_live_...` in an API design document. The literal
+# trailing ellipsis is part of the text — this is an illustrative curl example
+# for a proposed per-tenant key format, not an issued credential.
+docs/sub-plans/api/apis_design.md:curl-auth-header:685
+docs/sub-plans/api/apis_design.md:curl-auth-header:705

.pre-commit-config.yaml

@@ -42,6 +42,9 @@ repos:
         args: [--branch, main]
 
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.21.2
+    # Keep this reasonably current. Binaries built from older revs (v8.21.2
+    # and earlier) fail to load on recent macOS with a dyld "missing LC_UUID"
+    # abort, which surfaces as a hook crash (exit -6) rather than a finding.
+    rev: v8.30.1
     hooks:
       - id: gitleaks

CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Only names exported from `xrag.__all__` are covered by the version contract.
+Anything outside that surface is internal and may change in any release.
+
+## [Unreleased]
+
+### Added
+
+- DOCX image extraction: `DocxPicturePartitioner` and an `extract_images`
+  parser option (#61)
+- Image chunks in `SectionTableChunker` (#62)
+- LLM-generated image descriptions (#64)
+
+### Changed
+
+- Aligned retrieval and indexing defaults (#67)
+
+## [0.5.3] — 2026-05-05
+
+### Added
+
+- Navigational testset generator, with ADR-0003 recording the primary-chunk
+  evidence decision (#51)
+- Navigation questions in dataset generation (#54)
+- Per-category metric breakdown by `reasoning_type` (#52)
+- Append mode for the `eval create-dataset` CLI (#53)
+
+### Changed
+
+- Indexing now augments retrieval text instead of replacing it, per ADR-0002
+  (#45)
+
+## [0.5.2] — 2026-05-05
+
+### Fixed
+
+- Pin `openai_api_type=None` in the embedder to stop an environment variable
+  leaking into requests (#42)
+
+## [0.5.1] — 2026-05-05
+
+### Added
+
+- `ChunkMetadata` promoted to the public `__all__` surface (#40)
+
+## [0.5.0] — 2026-05-04
+
+### Added
+
+- Per-step `max_concurrency` for LLM-bound enrichers (#39)
+
+### Changed
+
+- **Breaking:** unified the chunk schema on the canonical V2 envelope and
+  `doc_id` (#37)
+
+## [0.4.1] — 2026-05-04
+
+### Added
+
+- `qdrant_api_key` parameter on `Xrag.__init__` (#29)
+
+## [0.4.0] — 2026-05-03
+
+### Changed
+
+- Explicit settings injection across the asymmetric boundary, recorded in
+  ADR-0001 (#26)
+
+## [0.3.0] — 2026-05-01
+
+### Changed
+
+- Library and client SDK cleanup pass across the public surface (#3)
+
+## [0.2.0] — 2026-04-27
+
+### Added
+
+- High-level async `Xrag` client with resource-namespaced operations
+  (`documents.*`, `retrievals.*`, `rag.*`)
+- Tenant binding via `client.for_tenant(...)`
+- Typed error hierarchy rooted at `XragError`
+- Split the local-PDF parser into its own `parser-unstructured-local-pdf` extra
+
+### Changed
+
+- Packaging moved to the hatch backend; the project publishes to PyPI as
+  `pyxrag` while the import name stays `xrag`
+- Renamed the engine repository from `fin-rag` to `xrag`
+
+[Unreleased]: https://github.com/henryle97/xrag/compare/v0.5.3...HEAD
+[0.5.3]: https://github.com/henryle97/xrag/compare/v0.5.2...v0.5.3
+[0.5.2]: https://github.com/henryle97/xrag/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/henryle97/xrag/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/henryle97/xrag/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/henryle97/xrag/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/henryle97/xrag/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/henryle97/xrag/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/henryle97/xrag/releases/tag/v0.2.0

CLAUDE.md

@@ -83,5 +83,3 @@ Single-context repo — `CONTEXT.md` and `docs/adr/` at the repo root (created l
 ## Rules
 
 - gh use the `henryle97` account. Run `gh auth switch -u henryle97` if needed
-
-