diff --git a/.gitignore b/.gitignore
index 5395464..9b13f87 100644
--- 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
index a92acac..8aeb836 100644
--- 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": ".klickd 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 AES-256-GCM and Argon2id key derivation (m=65536, t=3, p=4). No server is required.
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.
",
+ "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
index ddc6949..02e00b1 100644
--- 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
index 25c6ae1..2640cc0 100644
--- 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
index 89cf0eb..ef6e9ae 100644
--- 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
index 59c2ade..c2049b6 100644
--- 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
index 18c97c0..1899090 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
> *When it all .klickd*
-[](https://github.com/Davincc77/klickdskill)
+[](https://github.com/Davincc77/klickdskill)
[](https://creativecommons.org/publicdomain/zero/1.0/)
-[](https://doi.org/10.5281/zenodo.20320480)
+[](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
-[](https://github.com/Davincc77/klickdskill)
+[](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
index 8901331..4b2339c 100644
--- 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 — `
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
index 9e55ea7..4781bc3 100644
--- 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
index 9279902..e2d8925 100644
--- 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)
---
diff --git a/docs/releases/v4.0.0.md b/docs/releases/v4.0.0.md
new file mode 100644
index 0000000..3ab903a
--- /dev/null
+++ b/docs/releases/v4.0.0.md
@@ -0,0 +1,232 @@
+# .klickd v4.0.0 — Release Notes (final, GA)
+
+> **Status: GENERAL AVAILABILITY (release-prep).**
+> v4.0.0 is the first GA release of the `.klickd` v4 track.
+>
+> **This document accompanies the release-prep PR.** At the time of this
+> file landing, the following final gated actions have **not** been executed:
+> no git tag `v4.0.0`, no GitHub Release, no `@klickd/core@4.0.0` npm
+> publish (no `latest` dist-tag flip), no `klickd==4.0.0` PyPI publish, no
+> Zenodo deposit, no public announcement. Those happen after maintainer
+> review.
+
+---
+
+## TL;DR
+
+`v4.0.0` promotes the v4 surface from preview to GA. It is **additive over
+v3.5.1**: the wire envelope, crypto and AAD construction are unchanged
+(`klickd_version` stays `"3.0"`). 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
+
+`.klickd` is an **open-source security and continuity layer for every actor
+in AI**:
+
+- **For users** — privacy, ownership, and memory portability across models.
+- **For agents** — structured context and verified constraints (strict
+ payload schema, verification gates, human-veto signals).
+- **For developers** — Python and TypeScript reference SDKs, strict v4 JSON
+ Schemas, and a non-destructive v3.x → v4 migrator.
+- **For industry** — controlled, opt-in interoperability under a CC0 licence
+ with cross-implementation strict test vectors.
+
+> **One soul. Any model. Any agent.**
+
+`.klickd` complements (not replaces) provider security, model alignment, and
+application-level access control. v4.0.0 makes this layer normative and
+strict; it does not claim adoption as an industry standard, universal
+compatibility across all AI products, or guaranteed end-to-end security
+properties beyond those documented in `SPEC.md` and the v4 schemas.
+
+Backwards compatibility is preserved end-to-end:
+
+- A valid v3.x payload is a valid v4.0.0 payload (after running the
+ migrator, which only adds `payload_schema_version` and an optional
+ `migration_report`; it never overwrites caller-set v4 fields).
+- A valid v4.0.0 payload can still be loaded by a v3.x reader, which will
+ ignore the v4-only fields.
+
+---
+
+## What ships in v4.0.0
+
+### 1. SPEC normative v4
+
+`SPEC.md` is promoted to a normative v4 surface (covering `media_profile`,
+`verification_gates` + `human_veto`, migration / backward compatibility
+rules, error journal, risk thresholds, preflight checks, agent_core stub).
+The wire identifier (`klickd_version: "3.0"`) is unchanged; v4 opts in via
+the inner payload field `payload_schema_version`.
+
+Companion docs:
+
+- `docs/spec/MIGRATION_V3_TO_V4.md` — migration guide for content authors
+ and SDK consumers.
+- `docs/ux/V4-UX-SPEC.md` — product/UX surface for the wizard, error i18n
+ table, and persona examples.
+- `docs/roadmap/ROAD-TO-V4-GA.md` — backlog history; P0-1 to P0-6 are now
+ landed.
+
+### 2. Strict JSON Schemas (Draft 2020-12)
+
+- `schemas/klickd-payload-v4.schema.json`
+- `schema/klickd-v4.schema.json`
+
+These are **strict** (no permissive `additionalProperties: true` for known
+sections), but they preserve the wire-envelope crypto contract from v3.
+
+The permissive preview schemas
+(`schemas/klickd-payload-v4-preview.schema.json`,
+`schema/klickd-v4-preview.schema.json`) **remain shipped for one cycle** to
+ease transitions and will be deprecated in a later minor release.
+
+### 3. Reference SDKs aligned to v4 GA strict
+
+- Python: `klickd==4.0.0` (`packages/pypi/klickd/`)
+- TypeScript: `@klickd/core@4.0.0` (`packages/@klickd/core/`)
+
+Both SDKs:
+
+- expose a strict v4 validation entry point (Python: `klickd.validate.validate()`;
+ TypeScript: equivalent exported API),
+- preserve unknown / experimental fields on load and save,
+- expose the non-destructive `migrate` API.
+
+The `validate` extra remains optional for Python (requires `jsonschema`); the
+TypeScript SDK declares `ajv` as an optional peer dep.
+
+### 4. Non-destructive v3.x → v4 payload migrator (RFC-004)
+
+Both SDKs ship a `migrate(payload)` function that:
+
+- only sets fields that are absent (idempotent),
+- writes `payload_schema_version: "4.0.0"`,
+- produces a `migration_report` describing every applied transform and any
+ ambiguity it encountered,
+- **never overwrites caller-set v4 fields**,
+- is byte-stable across implementations on a fixed input.
+
+### 5. Strict cross-implementation v4 test vectors
+
+`tests/` contains positive and adversarial v4 GA strict vectors used by both
+`verify_vectors.py` (Python) and `verify_vectors.mjs` (Node). Vectors cover
+minimal payload, full payload, `media_profile`, `verification_gates`,
+`human_veto`, migration round-trip, and unknown-field passthrough.
+
+### 6. Community files
+
+CODE_OF_CONDUCT, issue templates and PR template (PR #47).
+
+---
+
+## Install
+
+```bash
+# Python — pinned to GA
+pip install "klickd==4.0.0"
+
+# Node.js / TypeScript — pinned to GA
+npm install @klickd/core@4.0.0
+```
+
+> **Note (publish gating).** At the moment of this release notes file
+> landing, the v4.0.0 artefacts have **not** been published to npm / PyPI
+> yet. The pinned commands above will start working once the maintainer
+> executes the publish step.
+
+---
+
+## Migration from v3.x
+
+```python
+from klickd import load_klickd, save_klickd, migrate
+
+payload = load_klickd(open("legacy.klickd", "rb").read(), passphrase="...")
+v4_payload, report = migrate(payload)
+save_klickd(v4_payload, open("modern.klickd", "wb"), passphrase="...")
+```
+
+```ts
+import { loadKlickd, saveKlickd, migrate } from "@klickd/core";
+
+const payload = await loadKlickd(legacyBytes, { passphrase });
+const { payload: v4Payload, report } = migrate(payload);
+await saveKlickd(v4Payload, { passphrase });
+```
+
+The migrator only adds fields. It does not change the wire envelope, the
+KDF, the AES-256-GCM cipher, or the AAD construction. A v3.x reader can
+still load the resulting file (and will ignore the v4 fields).
+
+See `docs/spec/MIGRATION_V3_TO_V4.md` for the full reader / writer matrix.
+
+---
+
+## Validation matrix
+
+| Suite | Tooling | Status |
+|------------------------------------------------|----------------------------|---------------|
+| Python vectors | `verify_vectors.py` | Required green |
+| Node vectors | `verify_vectors.mjs` | Required green |
+| Python SDK unit tests | `pytest` | Required green |
+| TypeScript SDK unit tests | `jest` | Required green |
+| Strict v4 schema validation (Python) | `scripts/validate_v4_schemas.py` | Required green |
+| Cross-impl v4 GA strict vectors | both verifiers | Required green |
+| Migrator round-trip vectors (v3.x → v4 → load) | both verifiers | Required green |
+| Secret scan (diff vs `main`) | local grep | No hit |
+
+The exact commands are codified in the PR description and in the existing
+GitHub Actions workflows.
+
+---
+
+## Compatibility
+
+| Reader | v3.x payload | v4.0.0 payload |
+|-------------------------------|--------------------|----------------------------------------|
+| v3.x reader (klickd 3.x) | Full support | Loads; ignores unknown v4 fields |
+| v4.0.0 reader (this release) | Full support (via migrator) | Full support |
+
+| Writer | Behaviour |
+|-------------------------------|--------------------------------------------------------------------------|
+| v3.x writer (klickd 3.x) | Continues to produce valid `klickd_version: "3.0"` envelopes |
+| v4.0.0 writer (this release) | Produces `klickd_version: "3.0"` envelopes with `payload_schema_version: "4.0.0"` |
+
+---
+
+## Known limitations
+
+- **No automatic Zenodo deposit.** The v4.0.0 version-specific DOI does not
+ exist until the maintainer manually deposits the release to Zenodo.
+ Until then, citation should use the concept DOI `10.5281/zenodo.20262530`
+ and qualify the version as "v4.0.0 (release-prep, no version-specific DOI
+ yet)".
+- **Preview schemas remain shipped for one cycle.** Consumers should
+ migrate to the strict schemas; the permissive preview schemas will be
+ deprecated in a later minor release.
+- **No production adoption claims.** This file documents what ships in
+ v4.0.0 and what is tested. It does not claim production deployments,
+ download counts, downstream integrations, or community adoption beyond
+ what is verifiable in this repository and on the existing public
+ registries.
+- **RFC-003 (Context Cost Benchmark) remains a local dry-run scaffold.**
+ Provider scoring is not wired up in this release.
+- **`agent_core` (RFC-006) remains future work** and is out of P0 scope for
+ v4.0.0 GA.
+
+---
+
+## Not in this PR (final gated public actions)
+
+These actions remain explicitly reserved for the maintainer, after review:
+
+1. Create annotated git tag `v4.0.0` on the merge commit.
+2. Publish a GitHub Release for `v4.0.0` (marked **Latest**).
+3. `npm publish @klickd/core@4.0.0` and set `dist-tag latest` to `4.0.0`.
+4. `twine upload` of `klickd==4.0.0` to PyPI.
+5. Deposit `v4.0.0` to Zenodo against concept DOI `10.5281/zenodo.20262530`
+ (a new version-specific DOI will be minted at that point).
+6. Any public announcement.
diff --git a/package.json b/package.json
index 9998481..26ec1a7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "klickdskill",
- "version": "4.0.0-preview.1",
+ "version": "4.0.0",
"private": true,
"description": "Reference implementation and test suite for the .klickd portable AI context format",
"type": "module",
@@ -17,7 +17,7 @@
"node": ">=18"
},
"license": "CC0-1.0",
- "author": "Vince C. (Klickd / Luxlearn, Luxembourg)",
+ "author": "Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)",
"repository": {
"type": "git",
"url": "https://github.com/Davincc77/klickdskill"
diff --git a/packages/@klickd/core/README.md b/packages/@klickd/core/README.md
index 96f3484..7624c1e 100644
--- a/packages/@klickd/core/README.md
+++ b/packages/@klickd/core/README.md
@@ -2,7 +2,7 @@
Official JavaScript/TypeScript library for reading and writing `.klickd` portable AI context files.
-**One soul. Any model. Any body.**
+**One soul. Any model. Any agent.** — open-source security and continuity layer for every actor in AI.
Official page for the open `.klickd` format → **[klickd.app/klickdskill](https://klickd.app/klickdskill)**
@@ -152,4 +152,4 @@ See `SPEC.md §33` and `examples/v4-preview/` for preview-track details.
## License
[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — Public Domain Dedication.
-Author: Vince C. (Luxlearn, Luxembourg)
+Author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)
diff --git a/packages/@klickd/core/package.json b/packages/@klickd/core/package.json
index 32f655b..d2d1f55 100644
--- a/packages/@klickd/core/package.json
+++ b/packages/@klickd/core/package.json
@@ -1,6 +1,6 @@
{
"name": "@klickd/core",
- "version": "4.0.0-preview.1",
+ "version": "4.0.0",
"description": "Official JavaScript/TypeScript library for reading and writing .klickd portable AI context files",
"keywords": [
"klickd",
@@ -15,7 +15,7 @@
"url": "https://github.com/Davincc77/klickdskill"
},
"license": "CC0-1.0",
- "author": "Vince C. (https://klickd.app)",
+ "author": "Vincenzo Cirilli (.klickd) (https://klickd.app)",
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.js",
diff --git a/packages/PACKAGE_SUMMARY.md b/packages/PACKAGE_SUMMARY.md
index c96c39c..e87a66e 100644
--- a/packages/PACKAGE_SUMMARY.md
+++ b/packages/PACKAGE_SUMMARY.md
@@ -1,6 +1,6 @@
# Klickd Package Scaffolds — Summary
-**Format:** .klickd v3.0 | **License:** CC0-1.0 | **Author:** Vince C. (Luxlearn, Luxembourg)
+**Format:** .klickd v3.0 | **License:** CC0-1.0 | **Author:** Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)
**Repo:** https://github.com/Davincc77/klickdskill | **DOI:** https://doi.org/10.5281/zenodo.20262530
---
diff --git a/packages/pypi/klickd/README.md b/packages/pypi/klickd/README.md
index 176bda6..371e549 100644
--- a/packages/pypi/klickd/README.md
+++ b/packages/pypi/klickd/README.md
@@ -2,7 +2,7 @@
Official Python library for reading and writing `.klickd` portable AI context files.
-**One soul. Any model. Any body.**
+**One soul. Any model. Any agent.** — open-source security and continuity layer for every actor in AI.
Official page for the open `.klickd` format → **[klickd.app/klickdskill](https://klickd.app/klickdskill)**
@@ -176,4 +176,4 @@ except KlickdError as e:
## License
[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — Public Domain Dedication.
-Author: Vince C. (Luxlearn, Luxembourg)
+Author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)
diff --git a/packages/pypi/klickd/pyproject.toml b/packages/pypi/klickd/pyproject.toml
index 4204523..e006e1c 100644
--- a/packages/pypi/klickd/pyproject.toml
+++ b/packages/pypi/klickd/pyproject.toml
@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
[project]
name = "klickd"
-version = "4.0.0a1"
+version = "4.0.0"
description = "Official Python library for reading and writing .klickd portable AI context files"
readme = "README.md"
license = {text = "CC0-1.0"}
-authors = [{name = "Vince C.", email = "Luxlearn@pm.me"}]
+authors = [{name = "Vincenzo Cirilli (.klickd)", email = "hello@klickd.app"}]
keywords = ["klickd", "ai-context", "portable", "memory", "encrypted"]
classifiers = [
- "Development Status :: 4 - Beta",
+ "Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
"Programming Language :: Python :: 3",
diff --git a/paper.md b/paper.md
index 9600c22..aa2fece 100644
--- a/paper.md
+++ b/paper.md
@@ -12,7 +12,7 @@ authors:
- name: Vincenzo Cirilli
affiliation: 1
affiliations:
- - name: Klickd / Luxlearn, Luxembourg
+ - name: .klickd / klickd.app, Luxembourg
index: 1
date: 20 May 2026
bibliography: paper.bib
diff --git a/scripts/release_bundle_inventory.sh b/scripts/release_bundle_inventory.sh
new file mode 100755
index 0000000..c8fa844
--- /dev/null
+++ b/scripts/release_bundle_inventory.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# release_bundle_inventory.sh — v4.0.0 release-prep helper.
+#
+# Generates a local, deterministic inventory and SHA256SUMS for the v4.0.0
+# bundle artefacts. Output goes to /release-artifacts/v4.0.0/, which
+# is .gitignored and never committed.
+#
+# This script does NOT publish anything. It only produces local artefacts
+# for the maintainer to inspect before any gated publish (npm / PyPI /
+# Zenodo / git tag / GitHub Release).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="4.0.0"
+OUT_DIR="${ROOT}/release-artifacts/v${VERSION}"
+
+mkdir -p "${OUT_DIR}"
+
+cd "${ROOT}"
+
+echo "==> Building npm package @klickd/core@${VERSION}"
+if [ -d "packages/@klickd/core" ]; then
+ (
+ cd packages/@klickd/core
+ if [ -f package.json ]; then
+ npm pack --pack-destination "${OUT_DIR}" >/dev/null
+ fi
+ )
+fi
+
+echo "==> Building Python sdist + wheel for klickd==${VERSION}"
+if [ -d "packages/pypi/klickd" ]; then
+ (
+ cd packages/pypi/klickd
+ if [ -f pyproject.toml ]; then
+ python -m build --outdir "${OUT_DIR}" >/dev/null 2>&1 || \
+ echo " (skip: python -m build not available; install with 'pip install build')"
+ fi
+ )
+fi
+
+echo "==> Snapshotting key normative artefacts"
+# Copy referenceable files for the Zenodo deposit bundle.
+mkdir -p "${OUT_DIR}/spec"
+for f in SPEC.md SCHEMA_INDEX.md CHANGELOG.md README.md CITATION.cff .zenodo.json LICENSE; do
+ [ -f "${ROOT}/${f}" ] && cp "${ROOT}/${f}" "${OUT_DIR}/spec/"
+done
+
+mkdir -p "${OUT_DIR}/schemas"
+cp -f schema/klickd-v4.schema.json "${OUT_DIR}/schemas/" 2>/dev/null || true
+cp -f schemas/klickd-payload-v4.schema.json "${OUT_DIR}/schemas/" 2>/dev/null || true
+
+mkdir -p "${OUT_DIR}/release-notes"
+cp -f docs/releases/v4.0.0.md "${OUT_DIR}/release-notes/" 2>/dev/null || true
+
+echo "==> Generating SHA256SUMS"
+(
+ cd "${OUT_DIR}"
+ find . -type f ! -name SHA256SUMS -print0 \
+ | LC_ALL=C sort -z \
+ | xargs -0 sha256sum > SHA256SUMS
+)
+
+echo
+echo "Inventory written to: ${OUT_DIR}"
+echo "Contents:"
+ls -la "${OUT_DIR}"
+echo
+echo "SHA256SUMS (head):"
+head -20 "${OUT_DIR}/SHA256SUMS" || true
+echo
+echo "Done. These artefacts are local-only; they are not committed to the repo."