Host workspace repositories on Central Gitea

README.md

@@ -1,8 +1,64 @@
-# Quixos Protocol
+# Quixos protocol and capability compiler
 
-Shared protobuf definitions for Camino, quixos-orch, package descriptors, and
-future package runtime RPC.
+This package owns the shared protobuf APIs for Camino, `quixos-orch`, package
+runtimes, package descriptors, and generic runtime values. It also owns the v1
+capability authoring language and semantic compiler.
 
-This package owns the canonical proto source. Current services still generate
-local TypeScript bindings from these protos; the generated bindings here are
-available for later consolidation.
+## Capability language
+
+The grammar is `grammar/QuixosCapability.g4`. The parser lowers source into the
+parser-independent records in `src/capability-model`; validation then produces
+an immutable checked workspace JSON document. Runtime semantics do not depend
+on parse-tree shapes or declaration order.
+
+```sh
+nix develop
+quixos-capability-compile ../quixos-instance/workspaces/todo.capabilities.qx
+```
+
+The compiler validates exact identities, interface operation coverage,
+attachment ownership, native state/edge providers, package receiver and
+dependency-port requirements, constructors, and the exact runtime closure.
+Generics, interface composition, declarative forwarding, automatic
+relationship materialization, and first-class bundles are intentionally absent
+from v1.
+
+## Repository locks
+
+Every workspace, interface, and package repository carries a `quixos.lock`.
+It pins the exact Quixos toolchain revision plus exact Git sources for imported
+interfaces and packages. The v1 Git source is deliberately only a repository
+URL and full commit ID; the publisher-owned reachability tag and Nix fetch
+details are derived from those values.
+
+```sh
+quixos-lock-check quixos.lock
+qx resource publish
+```
+
+The second command runs from a jj checkout. It validates the lock, snapshots
+the current working-copy commit, and pushes the immutable tag
+`refs/tags/quixos-reachability/<commit>` without advancing an authoring
+bookmark.
+
+## Package descriptors
+
+Executable package metadata remains protobuf text format:
+
+```sh
+quixos-descriptor-check path/to/descriptor.quixos-package.txtpb
+```
+
+Descriptors identify exact package revisions and exported runtime symbols.
+The checked workspace binds interface operations to those exports and supplies
+their exact dependency ports.
+
+## Tests
+
+```sh
+nix shell nixpkgs#protobuf -c npm test
+```
+
+The suite covers parsing/diagnostics, source-order independence, ordinary call
+operations, semantic validation, exact closure/tree-shaking, private and shared
+attachments, package port injection, and constructors.