fix(governance): root CONTRIBUTING.adoc + real guix.scm (docs + packaging jobs)

.github/CONTRIBUTING.md

@@ -1,156 +1,7 @@
 # Contributing to Nexia-List
 
-## Development Setup
+The single source of truth is the root **[CONTRIBUTING.adoc](../CONTRIBUTING.adoc)**.
 
-Prerequisites: [Bun](https://bun.sh/) 1.3+ and
-[Rust](https://www.rust-lang.org/tools/install) stable (plus the
-`wasm32-unknown-unknown` target for WASM builds). Bun is the only JS
-toolchain — do not use npm/deno/yarn/pnpm. A Guix environment is
-provided via `guix.scm` (`guix` `shell`) if you prefer reproducible
-shells.
-
-``` bash
-# Clone the repository
-git clone https://github.com/hyperpolymath/nexia-list.git
-cd nexia-list
-
-# Install dependencies
-bun install --frozen-lockfile
-
-# Run the development server (http://localhost:5173)
-bun run dev
-
-# Build (ReScript + web bundle)
-bun run build
-
-# Verify setup
-bun run lint
-bun run test    # Rust core tests + UI tests
-```
-
-Equivalent `just` recipes exist: `just` `setup`, `just` `build`, `just`
-`test`, `just` `run`, `just` `check`.
-
-### Repository Structure
-
-    nexia-list/
-    ├── core/                # Rust core — notes, backlinks, search, JSON storage
-    ├── ui/                  # ReScript TEA-style UI (@rescript/react)
-    ├── scripts/             # Bun build/dev scripts
-    ├── web/                 # Browser entry + bundle output (dist/)
-    ├── desktop/             # OPTIONAL Gossamer shell (external sibling checkout;
-    │                        # not built in this repo's CI)
-    ├── docs/                # ADRs, reports
-    │   └── adr/             # Architecture decision records
-    ├── tests/               # Cross-cutting tests
-    ├── .well-known/         # Protocol files (ai.txt, security.txt, humans.txt)
-    ├── .machine_readable/   # Contractiles, STATE/META/ECOSYSTEM checkpoints,
-    │                        # and governance metadata (see below)
-    ├── .github/             # GitHub config and workflows
-    │   └── CONTRIBUTING.md  # This file
-    ├── CHANGELOG.md
-    ├── CODE_OF_CONDUCT.md
-    ├── LICENSE
-    ├── MAINTAINERS.adoc
-    ├── README.adoc
-    ├── ROADMAP.adoc
-    ├── SECURITY.md
-    ├── package.json         # Bun tasks and dependencies
-    ├── bun.lock             # Exact JavaScript dependency graph
-    └── Justfile             # Task runner recipes
-
-Governance and invariants are machine-readable: see
-[`.machine_readable/`](../.machine_readable/) (in particular
-`MUST.contractile` and `INTENT.contractile`) and
-[`0-AI-MANIFEST.a2ml`](../0-AI-MANIFEST.a2ml).
-
-’’’’’
-
-## How to Contribute
-
-### Reporting Bugs
-
-**Before reporting**: 1. Search existing issues 2. Check if it’s already
-fixed in `main` 3. Determine which perimeter the bug affects
-
-**When reporting**:
-
-Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and
-include:
-
-- Clear, descriptive title
-
-- Environment details (OS, versions, toolchain)
-
-- Steps to reproduce
-
-- Expected vs actual behaviour
-
-- Logs, screenshots, or minimal reproduction
-
-### Suggesting Features
-
-**Before suggesting**: 1. Check the [roadmap](../ROADMAP.adoc) 2. Search
-existing issues and discussions 3. Consider which perimeter the feature
-belongs to
-
-**When suggesting**:
-
-Use the [feature request
-template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
-
-- Problem statement (what pain point does this solve?)
-
-- Proposed solution
-
-- Alternatives considered
-
-- Which perimeter this affects
-
-### Your First Contribution
-
-Look for issues labelled:
-
-- [`good` `first`
-  `issue`](https://github.com/hyperpolymath/nexia-list/labels/good%20first%20issue)
-  — Simple Perimeter 3 tasks
-
-- [`help`
-  `wanted`](https://github.com/hyperpolymath/nexia-list/labels/help%20wanted)
-  — Community help needed
-
-- [`documentation`](https://github.com/hyperpolymath/nexia-list/labels/documentation)
-  — Docs improvements
-
-- [`perimeter-3`](https://github.com/hyperpolymath/nexia-list/labels/perimeter-3)
-  — Community sandbox scope
-
-’’’’’
-
-## Development Workflow
-
-### Branch Naming
-
-    docs/short-description       # Documentation (P3)
-    test/what-added              # Test additions (P3)
-    feat/short-description       # New features (P2)
-    fix/issue-number-description # Bug fixes (P2)
-    refactor/what-changed        # Code improvements (P2)
-    security/what-fixed          # Security fixes (P1-2)
-
-### Commit Messages
-
-We follow [Conventional Commits](https://www.conventionalcommits.org/):
-
-    <type>(<scope>): <description>
-
-    [optional body]
-
-    [optional footer]
-
-’’’’’
-
-## Questions?
-
-See MAINTAINERS.adoc for who to contact, and SECURITY.md for reporting
-vulnerabilities.
+(This file remains so the in-GitHub "Contributing" link resolves somewhere
+useful; content was consolidated and corrected 2026-09-22 — the previous copy
+referenced the retired ReScript pipeline.)

CONTRIBUTING.adoc

@@ -0,0 +1,84 @@
+= Contributing to Nexia-List
+:toc: macro
+
+[.badges]
+xref:README.adoc[README] · link:LICENSE[License (MPL-2.0)]
+
+toc::[]
+
+== Development setup
+
+Prerequisites:
+
+* **Rust** stable + the `wasm32-unknown-unknown` target
+* **Bun** 1.3.x — the only JS toolchain (no npm/yarn/pnpm/deno; see
+  `docs/adr/0004-bun-only-toolchain.adoc`)
+* Optionally **Guix** for a reproducible native shell: `guix shell -D -f guix.scm`
+  covers Rust + native link deps; Bun and the wasm target are added via the
+  pinned installer steps exactly as CI does (see comments in `guix.scm`).
+
+[source,bash]
+----
+git clone https://github.com/hyperpolymath/nexia-list.git
+cd nexia-list
+bun install --frozen-lockfile
+
+# Build the Rust wasm core (web/wasm/)
+bun run build        # = bun run build:wasm
+
+# Verify
+bun run lint
+bun run test         # cargo test (core) + bun test (wasm/UI contract suites)
+----
+
+Equivalent `just` recipes exist (`just setup`, `just build`, `just test`,
+`just check`) — see the Justfile.
+
+== Repository structure
+
+    nexia-list/
+    ├── core/                # Rust core — notes, backlinks, search, JSON storage, λδ (lambdadelta) substrate
+    ├── ui/                  # AffineScript (.affine) UI sources — hand-rolled TEA (Model/Msg/Update/View)
+    │   ├── src/             #   modules + plain-JS store sinks (fileio/idb/vault)
+    │   └── tests/           #   *Tests.affine (compile-checked) + *.test.js (live bun suites)
+    ├── scripts/             # Bun build scripts (build_wasm.js)
+    ├── web/                 # Browser statics + wasm core output (web/wasm/)
+    ├── guix.scm             # Guix dev shell (native toolchain side)
+    └── docs/                # design/ adrs/ decisions/ wikis/
+
+IMPORTANT: The UI was ported ReScript → **AffineScript** (PR #76). The
+AffineScript compiler currently offers `affinescript check` (compile-verify)
+only — there is **no web UI emitter yet**, so `ui-ci` verifies changed
+`.affine` files (added files gate hard; legacy modifications advisory) and UI
+web bundling is deferred. See
+`docs/decisions/ui-web-bundle-deferred-2026-09-22.adoc`. Do not re-add ReScript
+tooling or zombie deps (`rescript`, `@rescript/*`, `react*`).
+
+== Workflow (issues → PR)
+
+. Open or pick an issue; state scope in it.
+. Branch from `main` (`fix/<slug>` / `feat/<slug>`); PRs only — no direct
+  pushes to `main`.
+. Keep CI honest: a step that cannot run must not claim a pass. Advisory
+  skips are reported *loudly*, never silently green.
+. Workflows are managed by `gh actions-lock`: after editing any
+  `.github/workflows/*` file, regenerate `actions.lock` and keep all
+  third-party actions pinned (this repo enforces SHA-pins);
+  SPDX header required on workflow files.
+. Docs are AsciiDoc (`docs/`), wikis are Markdown pointers — update the
+  *current-truth* documents when behaviour changes; ADRs are historical and
+  append-only (write a superseding ADR instead of editing).
+
+== Style
+
+* Rust: `cargo fmt` + clippy clean before push (see `rust-ci`).
+* JS/scripts: Biome (`bun run lint`, `bun run fmt`).
+* All new source files carry an SPDX header (`SPDX-License-Identifier: MPL-2.0`).
+* Banned languages/toolchains in this estate: TypeScript, Python, Go, npm —
+  plugin/tooling code is plain JS (Bun), Rust, bash, or AffineScript.
+
+== Reporting bugs / security
+
+Bugs: open an issue with repro steps. Security: see `SECURITY.md` and the
+`.well-known/security.txt` — do **not** open a public issue for
+vulnerabilities.

guix.scm

@@ -0,0 +1,35 @@
+;; SPDX-License-Identifier: MPL-2.0
+;; Guix development environment for nexia-list.
+;; Usage: guix shell -D -f guix.scm
+;;
+;; Covers the native side of the toolchain: Rust (stable) + the C/native
+;; bits cargo links against (openssl, pkg-config) + git. Two pieces are
+;; intentionally NOT in Guix because they are not packaged upstream:
+;;   * Bun 1.3.x — installed via the pinned script (`curl -fsSL
+;;     https://bun.sh/install | bash -s "bun-v1.3.14"`), exactly as CI does.
+;;   * wasm32-unknown-unknown — added per-toolchain via
+;;     `rustup target add wasm32-unknown-unknown` (Guix's rust does not
+;;     ship the wasm std as a component).
+;; CI (rust-ci.yml / ui-ci.yml) is the source of truth for those steps.
+
+(use-modules (guix packages)
+             (guix build-system gnu)
+             (guix licenses)
+             (gnu packages base)
+             (gnu packages bash)
+             (gnu packages rust)
+             (gnu packages tls)
+             (gnu packages pkg-config)
+             (gnu packages version-control))
+
+(package
+  (name "nexia-list")
+  (version "0.1.0")
+  (source #f)
+  (build-system gnu-build-system)
+  (inputs (list coreutils bash git rust pkg-config openssl))
+  (synopsis "nexia-list — a3ml-native notebook")
+  (description "nexia-list: wasm-core notebook engine with an AffineScript UI
+and the lambdadelta (λδ) plugin substrate — part of the hyperpolymath ecosystem.")
+  (home-page "https://github.com/hyperpolymath/nexia-list")
+  (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))