@@ -37,6 +37,8 @@ shows the problem.
 
 <!--
 Stack traces, sketch payloads, query plans, or anything else that helps
-narrow it down. For security-sensitive bugs, please email the
-maintainer privately instead of filing here — see CONTRIBUTING.md.
+narrow it down. For security-sensitive bugs, use **GitHub Security
+Advisories** (GHSA) on the repository — do not email the maintainer
+and do not file public issues for security reports. See SECURITY.md
+for the GHSA-only intake policy.
 -->
@@ -5,10 +5,19 @@
 # Motivation
 
 <!--
-Why is this change needed? Link issues with `Fixes #N` or `Refs #N`.
-For larger changes, include a sentence on alternatives considered.
+Why is this change needed? What user-visible problem or internal
+shortcoming does it address? For larger changes, include a sentence on
+alternatives considered.
 -->
 
+# Changes
+
+<!-- Bullet list of the concrete changes in this PR. -->
+
+-
+-
+-
+
 # Test plan
 
 <!--
@@ -18,16 +27,40 @@ samkhya-bench.
 -->
 
 - [ ] `cargo fmt --all -- --check`
-- [ ] `cargo clippy --workspace --exclude samkhya-duckdb --exclude samkhya-py -- -D warnings`
-- [ ] `cargo test --workspace --exclude samkhya-duckdb --exclude samkhya-py`
+- [ ] `cargo clippy --workspace --exclude samkhya-duckdb --exclude samkhya-py --exclude samkhya-postgres --all-features -- -D warnings`
+- [ ] `cargo test --workspace --exclude samkhya-duckdb --exclude samkhya-py --no-fail-fast`
+- [ ] Added or updated tests for changed behavior
+- [ ] Public API changes are documented (rustdoc on the changed item)
+- [ ] **Industry-standard metrics applied** if this PR touches measurement code: BCa bootstrap CIs (Efron-Tibshirani 1993), Wilcoxon paired signed-rank (1945), BH-FDR correction (1995), q-error per Moerkotte VLDB 2009 — see `bench-results/METHODOLOGY.md`
 
-# Checklist
+# Naming-compliance checklist
 
-- [ ] Formatting passes (`cargo fmt --all -- --check`)
-- [ ] Clippy passes with `-D warnings`
-- [ ] Tests pass on `ubuntu-latest`-equivalent locally
-- [ ] Public API changes are documented (rustdoc on the changed item)
-- [ ] No new "learned" / "adaptive" / "AI" framing in user-facing text
-  (see `samkhya.md` §3 for the naming rules)
-- [ ] No new external dependencies without a one-line justification in
-  the PR description
+- [ ] No "learned" / "adaptive" / "AI" framing in primary user-facing
+  text (see [[feedback-samkhya-naming]] rule: prefer "portable" /
+  "feedback-driven" / "self-correcting" / "LLM-pluggable")
+- [ ] If this PR touches the `Corrector` trait surface, the
+  pluggable-corrector-backend framing (GBT default · TabPFN-2.5 ·
+  LLM TODO) is preserved (no single-backend framing in trait docs)
+
+# Breaking changes
+
+<!--
+samkhya is post-1.0. Public API and on-disk format changes are
+governed by `docs/SEMVER.md`. State the semver impact explicitly.
+-->
+
+- Breaking change? <!-- yes / no -->
+- Semver impact: <!-- patch (1.x.y) / minor (1.x.0) / major (2.0.0) -->
+- If yes, link the deprecation note and migration guidance:
+
+# Related issues
+
+<!--
+Reference issues with `Fixes #N` or `Refs #N`. List any companion PRs
+in sibling crates.
+-->
+
+---
+
+*By submitting this PR you agree to dual Apache-2.0 OR MIT licensing
+of your contribution.*
@@ -0,0 +1,105 @@
+cff-version: 1.2.0
+message: "If you use samkhya in academic work, please cite it as below."
+title: "samkhya: portable, feedback-driven cardinality correction for embedded analytical engines"
+abstract: >
+  samkhya is the engine-agnostic Rust SDK for feedback-driven cardinality
+  correction in embedded analytical engines. It provides a pluggable
+  `Corrector` trait (GBT default, TabPFN-2.5 opt-in, LLM TODO), an
+  `LpJoinBound` pessimistic envelope (strict-tighter than AGM by 40.95×
+  on star-5 join topologies, p<10⁻⁵), portable Iceberg Puffin sidecars
+  for five classical sketches (HLL, Bloom, Count-Min, equi-depth
+  histogram, 2D correlated histogram), and adapters into DataFusion,
+  DuckDB, Polars, Postgres, Iceberg, Arrow, and Python.
+authors:
+  - family-names: Singh
+    given-names: Prateek
+version: "1.0.0"
+date-released: "2026-05-17"
+license:
+  - Apache-2.0
+  - MIT
+repository-code: "https://github.com/singhpratech/samkhya"
+url: "https://github.com/singhpratech/samkhya"
+keywords:
+  - cardinality estimation
+  - query optimization
+  - DataFusion
+  - DuckDB
+  - Polars
+  - embedded analytics
+  - LpBound
+  - TabPFN
+  - feedback-driven
+  - Iceberg Puffin
+  - HyperLogLog
+  - Bloom filter
+  - Count-Min Sketch
+preferred-citation:
+  type: software
+  title: "samkhya: portable, feedback-driven cardinality correction for embedded analytical engines"
+  authors:
+    - family-names: Singh
+      given-names: Prateek
+  version: "1.0.0"
+  date-released: "2026-05-17"
+  url: "https://github.com/singhpratech/samkhya"
+  license:
+    - Apache-2.0
+    - MIT
+references:
+  - type: article
+    authors:
+      - family-names: Hollmann
+        given-names: Noah
+      - family-names: Müller
+        given-names: Samuel
+      - family-names: Eggensperger
+        given-names: Katharina
+      - family-names: Hutter
+        given-names: Frank
+    title: "TabPFN: A Transformer That Solves Small Tabular Classification Problems in a Second"
+    conference:
+      name: "International Conference on Learning Representations (ICLR)"
+    year: 2023
+  - type: article
+    authors:
+      - family-names: Atserias
+        given-names: Albert
+      - family-names: Grohe
+        given-names: Martin
+      - family-names: Marx
+        given-names: Dániel
+    title: "Size Bounds and Query Plans for Relational Joins"
+    conference:
+      name: "ACM SIGMOD-SIGACT-SIGART Symposium on Principles of Database Systems (PODS)"
+    year: 2008
+  - type: article
+    authors:
+      - family-names: Leis
+        given-names: Viktor
+      - family-names: Gubichev
+        given-names: Andrey
+      - family-names: Mirchev
+        given-names: Atanas
+      - family-names: Boncz
+        given-names: Peter
+      - family-names: Kemper
+        given-names: Alfons
+      - family-names: Neumann
+        given-names: Thomas
+    title: "How Good Are Query Optimizers, Really?"
+    conference:
+      name: "VLDB"
+    year: 2015
+  - type: article
+    authors:
+      - family-names: Moerkotte
+        given-names: Guido
+      - family-names: Neumann
+        given-names: Thomas
+      - family-names: Steidl
+        given-names: Gabriele
+    title: "Preventing Bad Plans by Bounding the Impact of Cardinality Estimation Errors"
+    conference:
+      name: "VLDB"
+    year: 2009
@@ -0,0 +1,45 @@
+# Code of Conduct
+
+samkhya adopts version 2.1 of the **Contributor Covenant** as its
+community code of conduct. Read the full text here:
+
+  https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+
+A short summary: contributors, maintainers, and anyone else
+participating in this project — through issues, pull requests,
+discussions, code review, or any other channel — agree to treat each
+other with respect. Disagreement on technical decisions is welcome and
+expected; personal attacks, demeaning language, and conduct that makes
+participation hostile are not.
+
+## Scope
+
+This Code of Conduct applies in all project spaces (this repository,
+its issue tracker, its pull-request review threads, any associated
+chat) and when an individual is representing the project in public.
+
+## Reporting
+
+If you experience or witness behavior in a samkhya space that is
+inconsistent with the Contributor Covenant, report it to the
+maintainer via a private GitHub security advisory at:
+
+  https://github.com/singhpratech/samkhya/security/advisories/new
+
+Reports are read by the maintainer only and treated confidentially.
+The maintainer will respond within a week of receipt.
+
+## Enforcement
+
+The maintainer follows the **Contributor Covenant v2.1 Enforcement
+Guidelines** when responding to reports. The four-step ladder
+(correction → warning → temporary ban → permanent ban) is documented
+in the linked covenant text.
+
+## Attribution
+
+This Code of Conduct is the Contributor Covenant version 2.1, used
+under its
+[Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/).
+
+The full text and the FAQ are at <https://www.contributor-covenant.org>.
@@ -1,8 +1,12 @@
 # Contributing to samkhya
 
-Thanks for your interest in samkhya. The project is pre-alpha and the
-public surface is still in flux, so the most useful contributions right
-now are:
+Thanks for your interest in samkhya. The project is **v1.0+ stable**.
+The public Rust API, on-disk formats (Puffin sidecar layout, sketch
+payload codecs, SQLite feedback-store schema), and CLI flags are
+covered by semver — see [`docs/SEMVER.md`](./docs/SEMVER.md) for the
+governance rules and [`CHANGELOG.md`](./CHANGELOG.md) for the
+authoritative release log. Useful contributions land in any of the
+following buckets:
 
 - Bug reports against `samkhya-core` sketches (HLL, Bloom) and the
   `ColumnStats` shape.
@@ -188,10 +192,9 @@ maintainer is a single author and reviews land in batches.
 ## Architecture
 
 For a high-level tour of the workspace and the design decisions that
-shaped it, see `samkhya.md` §3. A dedicated `ARCHITECTURE.md` will land
-once the major subsystems (Puffin I/O, feedback recorder, LpBound
-envelope) have first implementations — when it exists, it will be
-linked here.
+shaped it, see [`ARCHITECTURE.md`](./ARCHITECTURE.md). The major
+subsystems (Puffin I/O, feedback recorder, LpBound envelope) are all
+implemented and documented there.
 
 The short version:
 
 
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prateek Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.