Davincc77 · Davincc77 · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,8 @@ __pycache__/
 # Node
 node_modules/
 dist/
+
+# Release-prep local artefacts (npm pack, python build, SHA256SUMS).
+# Never committed to the repo; produced on demand by
+# scripts/release_bundle_inventory.sh for maintainer inspection.
+release-artifacts/
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,12 +1,12 @@
 {
-  "title": ".klickd — An Open Encrypted File Format for Portable AI User Context",
-  "version": "3.5.1",
+  "title": ".klickd v4.0.0 — An Open Encrypted File Format for Portable AI User Context",
+  "version": "4.0.0",
   "upload_type": "software",
-  "description": "<p><strong>.klickd</strong> is an open, encrypted file format for portable AI user context. A single JSON document travels with the user across AI models and sessions. The payload is encrypted client-side with <strong>AES-256-GCM</strong> and <strong>Argon2id</strong> key derivation (m=65536, t=3, p=4). No server is required.</p><p>This deposit contains the reference specification (SPEC.md), reference implementations (Python and TypeScript), JSON Schemas (Draft 2020-12), cross-implementation test vectors, and a benchmark evaluation framework.</p>",
+  "description": ".klickd is an open-source security and continuity layer for every actor in AI: a portable, encrypted file format for user context that travels across AI models, agents and sessions. For users, it provides privacy, ownership and memory portability. For agents, it provides structured context and verified constraints. For developers, it provides reference SDKs, strict JSON Schemas and a non-destructive payload migrator. For industry, it provides controlled, opt-in interoperability under a CC0 licence. One soul. Any model. Any agent. A .klickd file is a single JSON document encrypted client-side with AES-256-GCM and Argon2id key derivation (m=65536, t=3, p=4); no server is required. Version 4.0.0 is the first general-availability release of the v4 track: it ships a normative SPEC for v4, strict JSON Schemas (Draft 2020-12), aligned Python and TypeScript reference SDKs, a non-destructive v3.x to v4 payload migrator, and cross-implementation strict test vectors. The wire envelope remains klickd_version 3.0 (unchanged crypto and AAD); v4 is signaled inside the payload via payload_schema_version 4.0.0. This deposit contains the reference specification (SPEC.md), reference implementations (Python and TypeScript), JSON Schemas, strict cross-implementation test vectors, the migrator, and a benchmark evaluation framework. This deposit does not claim adoption as an industry standard, universal compatibility across all AI products, or guaranteed end-to-end security beyond what is documented in SPEC.md and the v4 schemas.",
   "creators": [
     {
-      "name": "C., Vince",
-      "affiliation": "Klickd / Luxlearn, Luxembourg"
+      "name": "Cirilli, Vincenzo (.klickd)",
+      "affiliation": ".klickd / klickd.app, Luxembourg"
     }
   ],
   "access_right": "open",
@@ -26,7 +26,8 @@
     "JSON Schema",
     "interoperability",
     "agent memory",
-    "soul handoff"
+    "soul handoff",
+    "v4"
   ],
   "related_identifiers": [
     {
@@ -52,9 +53,15 @@
       "relation": "isVersionOf",
       "scheme": "doi",
       "resource_type": "software"
+    },
+    {
+      "identifier": "10.5281/zenodo.20320480",
+      "relation": "isNewVersionOf",
+      "scheme": "doi",
+      "resource_type": "software"
     }
   ],
   "communities": [],
   "language": "eng",
-  "notes": "Draft metadata for future Zenodo deposits. Communities intentionally left empty until known."
+  "notes": "Final v4.0.0 release metadata. Description is plain text (no HTML) for portability. Version-specific DOI for v4.0.0 will be minted by Zenodo upon deposit."
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,82 @@ Versions follow: `envelope_version (skill_revision)`.
 
 ---
 
+## v4.0.0 (GA) — 2026-05-25 — final v4 general availability (release-prep, not published)
+
+> **Status: RELEASE-PREP (PR open).** No git tag, no GitHub Release, no npm
+> publish (no `latest` dist-tag flip), no PyPI publish, no Zenodo deposit yet.
+> Those remain final gated public actions after maintainer review.
+>
+> v4.0.0 is the first general-availability release of the v4 track. The wire
+> envelope stays at `klickd_version: "3.0"` (crypto, AAD and KDF unchanged);
+> v4 is signalled inside the payload via
+> `payload_schema_version: "4.0.0"`. v3.x readers MUST ignore unknown
+> fields; v4 readers MUST preserve them verbatim.
+>
+> **Positioning (v4).** `.klickd` is positioned as an open-source security
+> and continuity layer for every actor in AI: users (privacy / ownership /
+> memory portability), agents (structured context / verified constraints),
+> developers (schemas / SDKs / migration) and industry (controlled,
+> opt-in interoperability). Tagline: *One soul. Any model. Any agent.*
+> v4.0.0 makes this layer normative and strict; it does not claim adoption
+> as an industry standard or universal cross-product compatibility.
+
+### What ships in v4.0.0
+
+- **SPEC normative v4** — `SPEC.md` promoting v4 wording from preview to
+  normative; `klickd_version: "3.0"` stays the wire identifier; the v4
+  surface is signalled via `payload_schema_version`.
+- **Strict JSON Schemas (Draft 2020-12)** — `schemas/klickd-payload-v4.schema.json`
+  and `schema/klickd-v4.schema.json`; coexist with v4 preview schemas for
+  one cycle.
+- **Reference SDKs aligned to v4 GA strict** — Python `klickd==4.0.0`
+  (`packages/pypi/klickd/`) and TypeScript `@klickd/core@4.0.0`
+  (`packages/@klickd/core/`). Public surface for v4 sections, strict
+  validation entrypoint, and preservation of unknown fields.
+- **Non-destructive v3.x → v4 payload migrator** (RFC-004) — exposed in
+  both SDKs; produces a `migration_report` and never overwrites caller-set
+  v4 fields.
+- **Strict cross-implementation v4 test vectors** — positive and adversarial,
+  verified by `verify_vectors.py` (Python) and `verify_vectors.mjs` (Node).
+- **Community files** — CODE_OF_CONDUCT, issue templates, PR template
+  (landed in #47).
+
+### Distribution version mapping (release-prep)
+
+| Channel    | Version target                                       | Notes                                                                       |
+|------------|------------------------------------------------------|-----------------------------------------------------------------------------|
+| git tag    | `v4.0.0`                                             | NOT created in this PR; final gated action.                                 |
+| npm        | `@klickd/core@4.0.0`                                 | NOT published in this PR; `latest` flip is a final gated action.            |
+| PyPI       | `klickd==4.0.0`                                      | NOT published in this PR; final gated action.                               |
+| Zenodo     | new version of concept DOI `10.5281/zenodo.20262530` | NOT deposited in this PR; final gated action.                               |
+
+### Backward compatibility
+
+- Wire envelope unchanged (`klickd_version: "3.0"`); v3.x readers continue
+  to load v4 files and MUST ignore unknown payload fields.
+- v3.5.1 deposit on Zenodo remains valid and citeable; v4.0.0 declares a
+  `isNewVersionOf` relationship to it.
+- The Python `klickd==3.x` series continues to load v4 payloads (round-trip)
+  but does not enforce the strict v4 schema; upgrading to `klickd==4.0.0`
+  is recommended to opt in to strict validation and to use the migrator.
+
+### Documentation
+
+- Release notes: [`docs/releases/v4.0.0.md`](docs/releases/v4.0.0.md).
+- Migration guide: [`docs/spec/MIGRATION_V3_TO_V4.md`](docs/spec/MIGRATION_V3_TO_V4.md).
+- Roadmap status: P0-1 to P0-6 all landed prior to this release-prep PR.
+
+### Not in this PR
+
+- No git tag.
+- No GitHub Release.
+- No npm publish, no `@klickd/core` `latest` dist-tag flip.
+- No PyPI publish.
+- No Zenodo deposit; no v4.0.0 version-specific DOI yet.
+- No public announcements.
+
+---
+
 ## Unreleased — docs-only — RFC promotions toward v4 GA
 
 > **Status: DOCS-ONLY / NON-NORMATIVE.** No SDK, schema, or vector change.

diff --git a/CITATION.cff b/CITATION.cff
@@ -8,22 +8,22 @@ abstract: >-
   AES-256-GCM and Argon2id key derivation. No server is required.
 type: software
 authors:
-  - family-names: "C."
-    given-names: "Vince"
-    affiliation: "Klickd / Luxlearn, Luxembourg"
+  - family-names: "Cirilli"
+    given-names: "Vincenzo"
+    name-suffix: ".klickd"
+    affiliation: ".klickd / klickd.app, Luxembourg"
 repository-code: "https://github.com/Davincc77/klickdskill"
 url: "https://klickd.app"
 license: CC0-1.0
-version: "3.5.1"
-date-released: "2026-05-22"
-doi: "10.5281/zenodo.20320480"
+version: "4.0.0"
+date-released: "2026-05-25"
 identifiers:
-  - type: doi
-    value: "10.5281/zenodo.20320480"
-    description: "Version-specific DOI for v3.5"
   - type: doi
     value: "10.5281/zenodo.20262530"
     description: "Concept DOI (all versions)"
+  - type: doi
+    value: "10.5281/zenodo.20320480"
+    description: "Version-specific DOI for v3.5.1"
 keywords:
   - portable-ai-memory
   - ai-context

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -79,4 +79,4 @@ preservation, not strict v4 business semantics.
 
 ## Contact
 
-Questions? Open a GitHub issue or email **Luxlearn@pm.me**.
+Questions? Open a GitHub issue or email **hello@klickd.app**.
diff --git a/PITCH.md b/PITCH.md
@@ -2,7 +2,7 @@
 
 **An open encrypted file format for portable AI identity**
 
-Klickd / Luxlearn — Luxembourg — 2026
+.klickd / klickd.app — Luxembourg — 2026
 DOI: [10.5281/zenodo.20262530](https://doi.org/10.5281/zenodo.20262530)
 
 ---
@@ -139,8 +139,8 @@ The goal is adoption. If `.klickd` becomes the standard, every AI user on earth
 
 ## Contact
 
-Vince C. — Klickd / Luxlearn, Luxembourg
-Luxlearn@pm.me
+Vincenzo Cirilli (.klickd) — klickd.app, Luxembourg
+hello@klickd.app
 https://github.com/Davincc77/klickdskill
 DOI: 10.5281/zenodo.20262530
 

diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 > *When it all .klickd*
 
-[![.klickd version](https://img.shields.io/badge/.klickd-v3.5.1-0066CC?style=flat-square&logo=json)](https://github.com/Davincc77/klickdskill)
+[![.klickd version](https://img.shields.io/badge/.klickd-v4.0.0-0066CC?style=flat-square&logo=json)](https://github.com/Davincc77/klickdskill)
 [![License: CC0](https://img.shields.io/badge/License-CC0%201.0-lightgrey?style=flat-square)](https://creativecommons.org/publicdomain/zero/1.0/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20320480.svg)](https://doi.org/10.5281/zenodo.20320480)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20262530.svg)](https://doi.org/10.5281/zenodo.20262530)
 
 **Official page for the open `.klickd` format → [klickd.app/klickdskill](https://klickd.app/klickdskill)**
 
@@ -20,12 +20,28 @@ You explain your level. Your goals. Your context. Then the session ends — and
 
 ---
 
+## Positioning (v4)
+
+`.klickd` is an **open-source security and continuity layer for every actor in AI**.
+
+- **For users** — privacy, ownership, and memory portability: your context is a file on your device, encrypted client-side, and follows you across models.
+- **For agents** — structured context and verified constraints: a strict schema for identity, preferences, gates and human-veto signals that an agent can read without inventing them.
+- **For developers** — schemas, SDKs and a non-destructive migrator: Python (`klickd`) and TypeScript (`@klickd/core`) reference implementations, strict v4 JSON Schemas (Draft 2020-12), and a v3.x → v4 payload migrator.
+- **For industry** — controlled, opt-in interoperability: a CC0 format with cross-implementation strict test vectors, so independent readers and writers can interoperate without ceding control of state to any single vendor.
+
+> **One soul. Any model. Any agent.**
+
+`.klickd` does not replace provider security, model alignment, or application-level access control; it complements them by giving the user-state layer a portable, verifiable shape.
+
+---
+
 ## What it looks like
 
 ```json
 {
-  "klickd_version": "3.5.1",
-  "created_at": "2026-05-21T00:00:00Z",
+  "klickd_version": "3.0",
+  "payload_schema_version": "4.0.0",
+  "created_at": "2026-05-25T00:00:00Z",
   "encrypted": false,
   "domain": "education",
   "user_preferences": "You are continuing a session with a learner working on calculus. Resume as if you have been here from the start."
@@ -59,7 +75,7 @@ They all require a running server, a Docker container, or an API key. Your memor
 ## The numbers
 
 Benchmarked across 23 subjects, 115 profiles. Scorer: `qwen/qwen3-32b` via Groq.  
-Full methodology: [DOI 10.5281/zenodo.20320480](https://doi.org/10.5281/zenodo.20320480)
+Full methodology (v3.5.1 deposit, still applicable to v4.0.0 payload semantics): [DOI 10.5281/zenodo.20320480](https://doi.org/10.5281/zenodo.20320480)
 
 | Sequence | What was tested | Δ WITH vs WITHOUT |
 |---|---|---|
@@ -97,7 +113,7 @@ npm install @klickd/core
 | [`examples/student_fr.klickd`](examples/student_fr.klickd) | French high-school student, maths, Socratic mode |
 | [`examples/professional_en.klickd`](examples/professional_en.klickd) | Mid-level developer upskilling into ML |
 | [`examples/family_plan.klickd`](examples/family_plan.klickd) | Child profile with ADHD support and shared family context |
-| [`examples/minimal.klickd`](examples/minimal.klickd) | Cold start — 5 fields only, valid v3.5 |
+| [`examples/minimal.klickd`](examples/minimal.klickd) | Cold start — minimal valid v3.x payload (forward-compatible with v4.0.0) |
 | [`examples/full_v34.klickd`](examples/full_v34.klickd) | Full reference file — all fields populated |
 
 ---
@@ -129,7 +145,9 @@ print('Valid.')
 "
 ```
 
-Schema: [`schema/klickd-v3.4.schema.json`](schema/klickd-v3.4.schema.json)
+Schemas:
+- v4.0.0 GA (strict): [`schema/klickd-v4.schema.json`](schema/klickd-v4.schema.json), [`schemas/klickd-payload-v4.schema.json`](schemas/klickd-payload-v4.schema.json)
+- v3.x (legacy, still valid): [`schema/klickd-v3.4.schema.json`](schema/klickd-v3.4.schema.json)
 
 ---
 
@@ -161,11 +179,11 @@ For most real workloads the useful question is not "long context **or** portable
 
 ```bibtex
 @misc{klickd2026,
-  title  = {.klickd — Open Learner Context Format, v3.5},
+  title  = {.klickd — Open Encrypted Format for Portable AI User Context, v4.0.0},
   author = {Cirilli, Vincenzo},
   year   = {2026},
-  doi    = {10.5281/zenodo.20320480},
-  url    = {https://doi.org/10.5281/zenodo.20320480}
+  doi    = {10.5281/zenodo.20262530},
+  url    = {https://doi.org/10.5281/zenodo.20262530}
 }
 ```
 
@@ -174,7 +192,7 @@ For most real workloads the useful question is not "long context **or** portable
 ## Badge
 
 ```markdown
-[![.klickd compatible](https://img.shields.io/badge/.klickd-v3.5%20compatible-0066CC?style=flat-square&logo=json)](https://github.com/Davincc77/klickdskill)
+[![.klickd compatible](https://img.shields.io/badge/.klickd-v4.0.0%20compatible-0066CC?style=flat-square&logo=json)](https://github.com/Davincc77/klickdskill)
 ```
 
 ---
@@ -183,19 +201,19 @@ For most real workloads the useful question is not "long context **or** portable
 
 [`SPEC.md`](SPEC.md) — encryption (AES-256-GCM), all field references, teaching modes, Soul Handoff, JSON Injection Guard, benchmark namespace, memory decay, shared context, versioning policy.
 
-### Looking ahead — `.klickd v4` preview (non-normative, not GA)
-
-The current and recommended production format is **v3.5.1**. In parallel, the repository hosts a **preview track** for the next iteration of the same `.klickd` standard family:
+### Current GA — `.klickd v4.0.0`
 
-- Spec: [`SPEC.md` §33 — `.klickd` v4 Preview](SPEC.md) (non-normative, additive over v3.5.1)
-- Permissive schemas: [`schemas/klickd-payload-v4-preview.schema.json`](schemas/klickd-payload-v4-preview.schema.json), [`schema/klickd-v4-preview.schema.json`](schema/klickd-v4-preview.schema.json)
-- Design source: RFCs under [`docs/rfcs/`](docs/rfcs/) (`media_profile`, `verification_gates` + `human_veto`, migration & backward compatibility) and the [Context Cost Benchmark](benchmarks/context_cost/RFC.md)
-- Minimal example: [`examples/v4-preview/minimal.klickd`](examples/v4-preview/minimal.klickd)
+The current and recommended production format is **v4.0.0**. The wire envelope stays at `klickd_version: "3.0"` (unchanged crypto and AAD); v4 is signalled inside the payload via `payload_schema_version: "4.0.0"`. v3.x readers MUST ignore unknown fields; v4 readers MUST preserve them verbatim.
 
-The preview targets `v4.0.0-preview.1`. No SDK release, no npm / PyPI / Zenodo publication, and no git tag are associated with it. v3.x readers MUST ignore preview fields; v4-preview readers MUST preserve unknown fields verbatim.
+- Spec: [`SPEC.md`](SPEC.md) — normative v4 surface (additive over v3.5.1).
+- Strict JSON Schemas (Draft 2020-12): [`schemas/klickd-payload-v4.schema.json`](schemas/klickd-payload-v4.schema.json), [`schema/klickd-v4.schema.json`](schema/klickd-v4.schema.json)
+- Reference SDKs (4.0.0): [`packages/pypi/klickd/`](packages/pypi/klickd/) (Python), [`packages/@klickd/core/`](packages/@klickd/core/) (TypeScript / JavaScript)
+- Migrator (v3.x → v4, non-destructive): see `migrate` API in both SDKs.
+- Migration guide: [`docs/spec/MIGRATION_V3_TO_V4.md`](docs/spec/MIGRATION_V3_TO_V4.md)
+- Cross-implementation strict vectors: [`tests/`](tests/) and the two `verify_vectors.*` runners.
+- Final release notes: [`docs/releases/v4.0.0.md`](docs/releases/v4.0.0.md)
 
-- Draft release notes: [`docs/releases/v4.0.0-preview.1.md`](docs/releases/v4.0.0-preview.1.md) — non-binding, prepared for a possible future preview release.
-- Publication checklist (not yet executed): [`docs/releases/CHECKLIST_v4_preview.md`](docs/releases/CHECKLIST_v4_preview.md).
+The previous v3.5.1 release remains valid and interoperable; v4.0.0 readers accept v3.x payloads via the migrator.
 
 ---
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -4,7 +4,7 @@
 
 If you discover a security vulnerability in the `.klickd` specification, reference implementations, or test vectors, please report it **privately** before any public disclosure:
 
-**Email:** Luxlearn@pm.me  
+**Email:** security@klickd.app  
 **Subject:** `[SECURITY] .klickd — <brief description>`
 
 We aim to respond within 72 hours and to publish a fix or advisory within 30 days of a confirmed issue.

diff --git a/SKILL.md b/SKILL.md
@@ -25,7 +25,7 @@ tools:
         type: string
         description: Path to the written /.memory/ directory
 license: CC0-1.0
-author: Vince C. (Klickd / Luxlearn, Luxembourg)
+author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)
 repo: https://github.com/Davincc77/klickdskill
 ---
 
@@ -1691,7 +1691,7 @@ User A discovers "Byzantine fault tolerance" in a distributed systems course
 
 | Role | Who | What |
 |---|---|---|
-| Maintainer | Klickd / Luxlearn | Reviews PRs, enforces privacy rules, manages versioning |
+| Maintainer | .klickd / klickd.app | Reviews PRs, enforces privacy rules, manages versioning |
 | Contributor | Any user | Opens PRs with anonymised templates |
 | Consumer | Any Jarvis | Pulls templates via HTTP GET |
 | Auditor | Community / whitehat | Reviews merged templates for quality and privacy compliance |
@@ -1802,7 +1802,7 @@ Released under **CC0 1.0 Universal** — public domain, no restrictions.
 
 Full legal text: https://creativecommons.org/publicdomain/zero/1.0/
 
-> To the extent possible under law, Klickd / Luxlearn has waived all copyright and related or neighbouring rights to the `.klickd` format specification. Published from Luxembourg.
+> To the extent possible under law, .klickd / klickd.app has waived all copyright and related or neighbouring rights to the `.klickd` format specification. Published from Luxembourg.
 
 ---
 

diff --git a/SPEC.md b/SPEC.md
@@ -2,7 +2,7 @@
 
 **Version:** 3.5.1  
 **License:** CC0 1.0 Universal (Public Domain)  
-**Maintainer:** Klickd / Luxlearn (Luxembourg)  
+**Maintainer:** .klickd / klickd.app (Luxembourg)  
 **Status:** Production — v3.5.1 (2026-05-22)
 
 ---
Original file line number	Diff line number	Diff line change
Expand Up		@@ -79,4 +79,4 @@ preservation, not strict v4 business semantics.

		## Contact

		Questions? Open a GitHub issue or email Luxlearn@pm.me.
		Questions? Open a GitHub issue or email hello@klickd.app.