Add SKEEP proposal docs module

CONTRIBUTING.md

@@ -1,15 +1,65 @@
 # Contribution Guide
 
-This project is currently in the setup phase, and a detailed contribution guide is not available yet.
+SKaiNET uses the Gitflow branching model described in
+[GITFLOW.adoc](GITFLOW.adoc). Keep ordinary fixes small, focused, and easy to
+review.
 
-We plan to expand this guide in the near future and cover topics such as:
+## When to Write an SKEEP
 
-* Clean and maintainable code
-* Contributions involving AI agents
-* Project structure and best practices
+SKEEP stands for SKaiNET Enhancement and Evolution Proposal. It is the
+project's KEEP-style track for changes that need a durable design record before
+or alongside implementation.
 
-We already use the Gitflow branching model, as described here: [Gitflow branching model](GITFLOW.adoc)
+Write an SKEEP when a change affects:
 
-For now, don’t hesitate to contribute. Please use common sense, aim to be helpful, and keep your contributions clear and well-structured. If you’re unsure about something, simple and practical improvements are always welcome.
+* public Kotlin APIs;
+* DSL syntax or semantics;
+* tensor dtype, shape, storage, or execution behavior;
+* compiler, graph export, or runtime integration;
+* compatibility or migration policy;
+* documentation structure for a long-lived feature area.
 
-Thank you for helping shape the project in its early stages 🙌
+You usually do not need an SKEEP for local bug fixes, internal refactors,
+dependency bumps, test-only changes, typo fixes, or implementation details that
+do not affect user-visible behavior.
+
+## SKEEP Procedure
+
+1. Create a feature branch. Prefer names like
+   `feature/skeep-001-tensor-collection-literals` or a similarly focused
+   feature name.
+2. Pick the next available three-digit number under
+   `docs/modules/skeep/pages/`. Do not reuse numbers, even if a proposal is
+   later rejected or superseded.
+3. Create the proposal as
+   `docs/modules/skeep/pages/NNN-short-title.adoc`.
+4. Add the proposal to `docs/modules/skeep/nav.adoc`.
+5. Add the proposal to the "Current Proposals" table in
+   `docs/modules/skeep/pages/index.adoc`.
+6. Start new proposals with `Status: Draft`. Use `Accepted`, `Implemented`,
+   `Superseded`, or `Rejected` only when maintainers have made that decision.
+7. Include the standard sections: summary, motivation, proposed design,
+   compatibility and migration notes, rollout plan, acceptance criteria, risks,
+   open questions, and references.
+8. If the proposal depends on external language or platform features, link the
+   relevant upstream documents and call out stability or compiler-flag
+   requirements.
+9. Keep implementation PRs connected to the SKEEP. The proposal explains the
+   shape of the decision; code changes prove and ship it.
+
+SKEEP files are part of the Antora docs component. The module is registered in
+`docs/antora.yml` and lives separately from the normal contributor docs so that
+design proposals can evolve as their own track.
+
+## General Contribution Expectations
+
+We plan to expand this guide over time. For now:
+
+* keep changes clear and well-scoped;
+* prefer project-local patterns over new abstractions;
+* add tests when behavior changes;
+* update docs when user-facing behavior changes;
+* keep generated or unrelated churn out of focused PRs.
+
+If you are unsure whether a change needs an SKEEP, open a small draft proposal
+or ask in the issue or PR before implementing the whole feature.

README.md

@@ -75,10 +75,10 @@ val d = c.relu()
 val source = JvmRandomAccessSource.open("model.gguf")
 StreamingGGUFReader.open(source).use { reader ->
     println("Tensors: ${reader.tensorCount}")
-    
+
     // Load specific tensor on demand (no whole-file loading)
     val bytes = reader.loadTensor("token_embd.weight")
-    
+
     // Or get a TensorStorage descriptor with encoding/placement metadata
     val storage = reader.loadTensorStorage("token_embd.weight")
 }
@@ -106,6 +106,20 @@ SKaiNET is a modular ecosystem. While this repository contains the core engine,
 | Examples and sample projects | [SKaiNET-examples](https://github.com/SKaiNET-developers/SKaiNET-examples) |
 | Interactive notebooks | [SKaiNET-notebook](https://github.com/SKaiNET-developers/SKaiNET-notebook) |
 | Eager backends & kernels (what runs where) | [Backends & kernels mindmap](docs/eager-execution-backends-and-kernels.md) |
+| Design proposals and long-lived API decisions | [SKEEP proposals](docs/modules/skeep/pages/index.adoc) |
+
+---
+
+## Contributing and Design Proposals
+
+Small fixes can go straight through the normal contribution flow described in
+[CONTRIBUTING.md](CONTRIBUTING.md) and [GITFLOW.adoc](GITFLOW.adoc).
+
+Use a SKEEP when a change affects public APIs, DSL syntax, tensor semantics,
+compiler/runtime integration, storage behavior, compatibility policy, or other
+decisions that need a durable design record. SKEEP files live under
+`docs/modules/skeep/pages/` and use three-digit numbering, starting with
+`001`.
 
 ---
 

docs/antora.yml

@@ -3,6 +3,7 @@ title: SKaiNET
 version: ~
 nav:
   - modules/ROOT/nav.adoc
+  - modules/skeep/nav.adoc
 
 # Component-level attributes flow to every page. Defined here so the
 # operator-design article (and any future page) can reference them

docs/modules/ROOT/pages/contributing/index.adoc

@@ -22,6 +22,8 @@ The Contributing section is for the engineer who:
 - Adds or replaces kernels in the CPU backend (scalar, Panama Vector,
   the planned native FFM provider).
 - Operates the self-hosted runner that publishes benchmark results.
+- Drafts or reviews durable API and architecture proposals in the
+  xref:skeep:index.adoc[SKEEP proposal track].
 
 Concretely:
 
@@ -32,6 +34,7 @@ Concretely:
 | xref:contributing/benchmarks.adoc[Engine benchmark program] | The Phoronix Test Suite / OpenBenchmarking publication path: methodology, manifest, lanes, CI workflow, replay.
 | xref:contributing/matmul-kernels.adoc[Reading the matmul benchmark] | What the published numbers mean — scalar vs. Panama vs. quantized regimes, roofline reasoning, and a checklist for interpreting any new measurement.
 | xref:contributing/register-bench-runner.adoc[Register a self-hosted bench runner] | The one-time operator setup that lights up the full-publish CI lane on a Linux x86 box.
+| xref:skeep:index.adoc[SKEEP proposal track] | How SKaiNET records long-lived API, DSL, runtime, compiler, storage, and compatibility proposals.
 |===
 
 == What this section deliberately does *not* cover
@@ -42,8 +45,9 @@ Concretely:
 - **What an operator does or how the public DSL works.** See
   xref:reference/operators/generated/index.adoc[Operator reference] and
   the Explanation pages.
-- **Issue reports, branch policy, or commit conventions.** Those live
-  in repo-root files: `CONTRIBUTING.md`, `GITFLOW.adoc`,
+- **Issue reports, branch policy, commit conventions, or the detailed
+  SKEEP authoring procedure.** Those live in repo-root files:
+  `CONTRIBUTING.md`, `GITFLOW.adoc`,
   `CHANGELOG.md`, `FAQ.md`. The published docs site intentionally
   does not duplicate them; they belong with the code.
 

docs/modules/skeep/nav.adoc

@@ -0,0 +1,4 @@
+.SKEEP
+* xref:skeep:index.adoc[About SKEEP]
+* Proposals
+** xref:skeep:001-tensor-collection-literals.adoc[SKEEP-001: Tensor collection literals]