capsium 0.1.2 → 0.3.0

data/README.adoc

@@ -9,27 +9,14 @@ content packages with ease.
 This gem provides a structured way to handle content, data, and metadata for
 various applications.
 
-
-== Testing out how it works
-
-Download the mn-samples-iso built site: https://github.com/metanorma/mn-samples-iso/actions/runs/8862815829/artifacts/1453746303[mn-samples-iso-Linux].
-
-Then run these commands:
+== Test it out!
 
 [source,bash]
 ----
-$ unzip mn-samples-iso-Linux.zip
-$ cd mn-samples-iso-Linux
-$ mkdir content
-$ mv index.html documents.xml documents content
-$ echo '{"name": "mn-samples-iso","version":"0.1.0"}' > metadata.json
-$ cd ..
-$ bundle exec capsium package pack -f mn-samples-iso-Linux
-Package created: mn-samples-iso-0.1.0.cap
-$ bundle exec capsium reactor serve mn-samples-iso-0.1.0.cap
-Starting server on http://localhost:8864
-[2024-06-05 14:56:41] INFO  WEBrick::HTTPServer#start: pid=8234 port=8864
-...
+$ wget https://github.com/capsiums/cap-story/releases/download/v0.9.0/story_of_claire-0.9.0.cap
+$ capsium reactor serve story_of_claire-0.9.0.cap
+$ open http://localhost:8864
+# => Read the story!
 ----
 
 == Installation
@@ -57,184 +44,558 @@ gem install capsium
 
 == What is a Capsium package?
 
-A Capsium package is a structured collection of content, data, metadata, and routing information. It is designed to encapsulate all resources needed for a particular application or service in a well-organized format. A package typically includes:
+A Capsium package is a structured collection of content, data, metadata, and
+routing information, distributed as a single `.cap` file (a ZIP archive, MIME
+`application/vnd.capsium.package`). The canonical layout:
 
-* **Content**: Static files like HTML, CSS, and JavaScript.
-* **Data**: Structured data files, such as YAML or JSON.
-* **Metadata**: Descriptive information about the package, such as its name, version, and dependencies.
-* **Routes**: Mapping of URLs to content or data endpoints.
-* **Storage**: Definitions for datasets and their sources, formats, and schemas.
+[source]
+----
+metadata.json     # REQUIRED, hand-authored
+manifest.json     # auto-generated at load/pack time when absent
+routes.json       # auto-generated when absent
+storage.json      # optional (only when datasets exist)
+security.json     # generated at pack time (SHA-256 checksums)
+authentication.json # optional (user authentication)
+content/          # served content root (URL space mirrors paths below it)
+data/             # datasets (optional)
+----
+
+Paths inside the configuration files are package-relative POSIX paths.
+
+* **metadata.json**: name (kebab-case), version (semver), description, guid
+  (URI) and uuid are required; author, license, repository, dependencies
+  (an object of `guid -> semver range`) are optional.
+* **manifest.json**: an object keyed by package-relative resource path, e.g.
+  `"content/index.html": { "type": "text/html", "visibility": "exported" }`.
+  Generated by scanning `content/` (MIME types via marcel) when absent.
+* **routes.json**: an optional top-level `index` plus a `routes` array. Route
+  kinds: `{path, resource}` for static files, `{path, dataset}` for datasets
+  (served under `/api/v1/data/<id>`). HTML files get two routes (basename and
+  full filename); the index HTML additionally gets `/`.
+* **storage.json**: dataset definitions under `storage.dataSets`, either
+  schema-backed files (`source`, `schemaFile`, `schemaType: json-schema`)
+  or SQLite (`databaseFile`, `table`). `storage.layers` declares overlay
+  layers (see "Layered storage" below).
+* **security.json**: `security.integrityChecks.checksums` holds a SHA-256 hex
+  digest for every file in the package except `security.json` itself and
+  `signature.sig`. When the package is signed, `security.digitalSignatures`
+  records `{ "publicKey", "signatureFile" }`.
+* **authentication.json**: optional user authentication (see
+  "Authentication" below): `authentication.basicAuth` and/or
+  `authentication.oauth2`.
+
+Legacy (pre-0.2) configuration files are still accepted on read and
+normalized to the canonical forms; writers emit only the canonical forms.
 
 == What is a Capsium reactor?
 
-A Capsium reactor is a runtime environment that serves Capsium packages. It reads the package configuration and starts a server that can handle HTTP requests according to the routes defined in the package. The reactor ensures that the content and data within the package are served correctly, allowing for easy integration and deployment of packaged applications.
+A Capsium reactor is a runtime environment that serves Capsium packages. It
+reads the package configuration and starts a server that can handle HTTP
+requests according to the routes defined in the package. The reactor verifies
+the package against `security.json` when present and rejects tampered
+packages. Dataset routes are served as JSON; static resources are served with
+`Cache-Control: public, max-age=31536000` (configurable). While serving, the
+reactor also answers the introspection endpoints described below.
 
 == CLI: Package
 
-To pack a package, you need to define the content, data, metadata, routes, and storage configurations. Once defined, you can use the Capsium command-line interface (CLI) to create and manage your packages.
+Capsium provides a CLI to help you pack and manage your packages.
 
-Capsium provides a CLI to help you pack and manage your packages. Here are some common commands:
+=== Packing a package
 
 [source,bash]
 ----
-# TODO: Create a new package
-# Full command
-capsium package new my_package
-# Shorthand
-capsium package my_package
+capsium package pack [--force/-f] path-to-package
+----
 
-# TODO: Add content to the package
-capsium package add content example.html example.css example.js
+This command generates `manifest.json`/`routes.json` when absent, writes
+`security.json` with SHA-256 checksums of every package file, and packs the
+directory into `{package-name}-{package-version}.cap` (name and version from
+`metadata.json`).
 
-# TODO: Add data to the package
-capsium package add data animals.yaml
+.Sample `pack` command
+====
+[source,bash]
+----
+capsium package pack -f spec/fixtures/bare-package
+----
+====
 
-# TODO: Add metadata to the package
-capsium package add metadata name=sample_package version=0.1.0
+=== Unpacking a package
 
-# TODO: Define routes for the package
-capsium package add route /=example.html /index=index.html /api/v1/data/animals={type:dataset,name:animals}
+[source,bash]
+----
+capsium package unpack bare-package-0.1.0.cap [-o/--output my_bare_package]
+----
 
-# TODO: Define storage for the package
-capsium package add storage datasets=[{name:animals,source:data/animals.yaml,format:yaml,schema:data/animals_schema.yaml}]
+When `-o` is omitted, the package is unpacked into a directory named after
+the `.cap` file.
+
+Extraction is zip-slip safe: entries whose names would escape the
+destination (absolute paths, drive letters, `..` segments) are rejected
+with `Capsium::Packager::UnsafeEntryError`.
+
+=== Validating a package
+
+[source,bash]
+----
+capsium package validate path-to-package-or-cap
 ----
 
-=== Packing a package
+Runs a per-check report and exits with status 1 on any failure:
+
+* metadata: required fields present and well-formed (kebab-case name, semver
+  version, URI guid, UUID)
+* manifest: every resource exists on disk
+* routes: route targets exist; dataset routes live under `/api/v1/data/`;
+  the index resolves to an existing HTML file
+* storage: dataset sources (and schemas) exist; dataset data passes
+  JSON-schema validation
+* security: checksums match when `security.json` is present
+* content: no external `http(s)` references in `content/` files
 
-To pack an existing Capsium package directory, use the following command:
+=== Inspecting a package
 
 [source,bash]
 ----
-capsium package pack [--force/-f] path-to-package
+capsium package info|manifest|routes|metadata|storage path-to-package [--store DIR]
 ----
 
-This command will pack your package into a single file with the
-filename:
+`info` additionally prints the resolved dependency tree for composite
+packages (declared GUID and range, resolved version, store `.cap`), see
+"Composite packages" below.
 
-* `{package-name}-{package-version}.cap`
-* where the name and version both come from `{package-path}/metadata.json`
+=== Signing a package
 
-.Sample `pack` command
-====
 [source,bash]
 ----
-capsium package pack -f spec/fixtures/bare_package
+capsium package sign path-to-package-or-cap --key private.pem [--cert cert.pem]
+----
+
+Signs the package with an RSA private key (minimum 2048 bits) using
+RSA-SHA256, per the packaging standard's digital signature clause. Signing
+is a post-pack step: `pack` drops signing artifacts, so sign the packed
+directory or the `.cap` file itself.
+
+The signed payload is the concatenation, in sorted package-relative path
+order, of the raw bytes of every file covered by the `security.json`
+integrity checksums — i.e. every package file except `security.json` and
+`signature.sig`. The signature over that payload is stored as raw bytes in
+`signature.sig`, the signer's public key PEM is embedded as
+`signature.pub.pem`, and `security.json` records:
+
+[source,json]
+----
+{
+  "security": {
+    "digitalSignatures": {
+      "publicKey": "signature.pub.pem",
+      "signatureFile": "signature.sig"
+    }
+  }
+}
+----
+
+When `--cert` is given, the X.509 certificate must match the private key,
+and the certificate's public key is embedded instead.
+
+The payload construction is openssl-compatible; to verify a signed package
+independently, concatenate the checksum-covered files in sorted order and
+run:
+
+[source,bash]
+----
+openssl dgst -sha256 -verify signature.pub.pem -signature signature.sig payload.bin
+----
+
+=== Verifying a package signature
+
+[source,bash]
+----
+capsium package verify-signature path-to-package-or-cap [--cert cert-or-public-key.pem]
+----
+
+Verifies the declared signature against the package contents (using the
+embedded public key, or the given certificate/public key) and exits with
+status 1 when the package is unsigned or the signature does not match.
+Packages that declare a signature are also verified automatically on load —
+a mismatch raises `Capsium::Package::Signer::SignatureMismatchError`, so a
+tampered signed package cannot be served by the reactor.
+
+=== Encrypting a package
+
+[source,bash]
+----
+capsium package encrypt path-to-package-or-cap --public-key public.pem -o encrypted.cap
 ----
-====
 
+Encrypts the whole package for the recipient's RSA public key (or X.509
+certificate), per the packaging standard's encryption clause: the
+encrypted `.cap` is a zip containing `metadata.json` (cleartext, so
+name/version stay readable), `signature.json` (the encryption envelope)
+and `package.enc` — the AES-256-GCM ciphertext of the inner plaintext
+`.cap` zip (content, configuration files, data). A random 256-bit data
+encryption key (DEK) encrypts the inner zip and is wrapped with the
+recipient's public key using RSA-OAEP with SHA-256:
 
+[source,json]
+----
+{
+  "encryption": {
+    "algorithm": "AES-256-GCM",
+    "keyManagement": "RSA-OAEP-SHA256",
+    "encryptedDek": "<base64>",
+    "iv": "<base64>",
+    "authTag": "<base64>"
+  }
+}
+----
+
+The OCB/OpenPGP alternatives mentioned by the standard are intentionally
+not implemented.
+
+=== Decrypting a package
+
+[source,bash]
+----
+capsium package decrypt encrypted.cap --private-key private.pem [-o decrypted.cap]
+----
+
+Decrypts an encrypted package with the recipient's RSA private key and
+writes the plaintext `.cap` (default output: `<name>-decrypted.cap`).
+Decryption fails with a typed error when the key does not match or the
+ciphertext was tampered with (GCM authentication). Loading an encrypted
+package without a key raises `Capsium::Package::Cipher::KeyRequiredError`
+— the reactor refuses to serve it.
+
+=== Testing a package
+
+[source,bash]
+----
+capsium package test path-to-package-or-cap
+----
+
+Runs the package's test suite declared in the Capsium testing YAML DSL
+(05x-testing): all `tests/*.yaml` files in the package, each holding a
+top-level `tests` list. Every test has a `name` and a `type`; the four
+supported types:
+
+* `route` — requests the URL path from a reactor started for the run and
+  checks `expected_status`, plus optional `response_contains` (body
+  substring) and `expected_content_type`. Absolute URLs are accepted;
+  only their path (and query) is used.
+* `file` — the file at `path` must exist in the package; optional
+  `contains` checks a content substring.
+* `data_validation` — the rows of `data_file` (format `json` or `yaml`)
+  must validate against the JSON schema at `schema_file`. Array data
+  validates row by row.
+* `config` — `config_file` (format `json` or `yaml`) must exist and
+  parse; the known package configs (`metadata.json`, `manifest.json`,
+  `routes.json`, `storage.json`, `security.json`) are additionally
+  validated against their canonical models.
+
+Example:
+
+[source,yaml]
+----
+tests:
+  - name: Home Route Test
+    type: route
+    url: "/home"
+    expected_status: 200
+    response_contains: "Welcome"
+
+  - name: Config File Exists
+    type: file
+    path: "metadata.json"
+
+  - name: JSON Data Validation
+    type: data_validation
+    format: json
+    data_file: "data/animals.json"
+    schema_file: "data/animals.schema.json"
+
+  - name: Metadata Config Validation
+    type: config
+    format: json
+    config_file: "metadata.json"
+----
+
+Each test is reported as `PASS`/`FAIL` with messages; the command exits
+with status 1 when any test fails (or a test definition is invalid).
 
 == CLI: Reactor
 
 === Starting a reactor on your package
 
-To start a Capsium reactor on your package, use the following command:
+[source,bash]
+----
+capsium reactor serve my_package.cap [--port 8864] [--store DIR] [--deploy deploy.json]
+----
+
+The reactor takes a local package directory or `.cap` file; serving
+directly from a URL is not supported. `--store` (or `CAPSIUM_STORE`)
+resolves composite-package dependencies; `--deploy` (or
+`CAPSIUM_DEPLOY`) points at the reactor-side `deploy.json` with
+authentication secrets (see "Authentication" below).
+
+=== Reactor introspection API
+
+While serving, the reactor answers the Monitoring HTTP API
+(ARCHITECTURE.md section 7) as `application/json`:
+
+[source]
+----
+GET /api/v1/introspect/metadata         # => {"packages": [{"name", "version", "author", "description"}]}
+GET /api/v1/introspect/routes           # => {"routes": [{"package", "routes": [{"method", "path"}]}]}
+GET /api/v1/introspect/content-hashes   # => {"contentHashes": [{"package", "hash"}]}
+GET /api/v1/introspect/content-validity # => {"contentValidity": [{"package", "valid", "lastChecked", "reason"?}]}
+----
+
+Non-GET methods on these paths are answered `405 Method Not Allowed`.
+
+`content-hashes` is the SHA-256 of the `.cap` blob when the package was
+served from one. For a directory source there is no blob, so the hash
+covers the canonical (sorted-key) JSON serialization of the package
+content checksums — the same data `security.json` integrityChecks carry.
+
+`content-validity` re-verifies the package against `security.json` on
+every request and reports the outcome with a UTC `lastChecked`
+timestamp; `reason` lists the integrity errors when `valid` is false.
+The entry also reports `signed` and `encrypted` status, plus
+`signatureValid` when the package declares a signature.
+
+== Layered storage
+
+`storage.layers` stacks overlay directories over `content/` (bottom ->
+top in declaration order), each mirroring the `content/` tree:
+
+[source,json]
+----
+{ "storage": { "layers": [
+    { "path": "base",    "writable": false, "visibility": "exported" },
+    { "path": "updates", "writable": true,  "visibility": "private" }
+] } }
+----
+
+A request resolves against layers from the TOP down; the first hit
+wins. Deletions are recorded as tombstones: a `.capsium-tombstones`
+JSON file (an array of `content/`-relative paths) in a writable layer;
+a tombstoned path resolves 404 even when a lower layer holds the file,
+while a file reappearing above the tombstone is served again. Packages
+without a `layers` config behave exactly as before (single implicit
+`content/` layer). `visibility: private` layers are hidden from
+dependent packages (see below), as are resources whose manifest
+visibility is `private`.
+
+== Composite packages
+
+`metadata.dependencies` maps a dependency GUID to a semver range
+(`>=1.0.0`, `^1.2.3`, `~1.2.3`, exact, `*`, `1.x`/`1.2.x`, partials,
+and comma/space conjunctions like `>=1.0.0, <2.0.0`). Dependencies
+resolve against a *package store* — a directory of
+`<name>-<version>.cap` files plus an optional `index.json` (GUID ->
+file) — given via `CAPSIUM_STORE` or `--store`; the newest satisfying
+version wins.
+
+On load, each resolved dependency's exported content becomes read-only
+layers below all of the dependent's own layers. Routes may address
+dependency content explicitly (`"resource": "<dependency-guid>/content/app.js"`)
+or declare route-inheritance attributes per 05x-routing: `remap`
+(replaces the serving path), `responseRewrite` (`body`, `headers`),
+`responseHeaders` (merged over served headers) and `requestHeaders`
+(parsed and exposed for forwarding reactors; this reactor serves
+statically, so they do not alter its responses). Referencing a
+dependency's private or missing resource is a load-time error, as are
+circular, missing or unsatisfiable dependencies.
 
 [source,bash]
 ----
-capsium reactor serve my_package.cap
+capsium package info my-composite-package --store ./store
+capsium reactor serve my-composite-package --store ./store
 ----
 
+== Authentication
 
-== Programmatically managing packages
+`authentication.json` enables user authentication (05x-authentication):
 
-You can also create, load, and use packages programmatically within your Ruby application.
+[source,json]
+----
+{ "authentication": {
+    "basicAuth": { "enabled": true, "passwdFile": "auth/.htpasswd", "realm": "capsium" },
+    "oauth2": { "enabled": true, "provider": "google", "clientId": "...",
+                "authorizationUrl": "...", "tokenUrl": "...", "userinfoUrl": "...",
+                "redirectPath": "/auth/callback", "scopes": ["openid", "email"] }
+} }
+----
 
-=== Creating packages
+When enabled, the reactor challenges every unauthenticated request
+(`401`, with `WWW-Authenticate: Basic realm="..."` when basicAuth is
+enabled) and verifies credentials against the htpasswd file. Supported
+hashes: bcrypt (`htpasswd -B`, via the `bcrypt` gem), Apache apr1 MD5
+and md5-crypt (`$apr1$`/`$1$`, pure Ruby), unsalted SHA-1 (`{SHA}`),
+and a platform `crypt(3)` fallback for the rest.
 
-[source,ruby]
+With OAuth2, `/auth/login` redirects to the provider with HMAC-signed
+state; the callback exchanges the code at `tokenUrl`, fetches the
+userinfo claims and establishes an HMAC-SHA256 signed session cookie
+(`capsium_session`, `HttpOnly; SameSite=Lax`). Provider errors during
+the exchange answer `502`; a tampered state answers `401`.
+
+Route-level `accessControl` on dataset routes is enforced after
+authentication — `401` unauthenticated, `403` when the identity lacks a
+required role:
+
+[source,json]
+----
+{ "path": "/api/v1/data/animals", "dataset": "animals",
+  "accessControl": { "roles": ["admin"], "authenticationRequired": true } }
 ----
-require 'capsium'
 
-package = Capsium::Package.new(
-  name: 'sample_package',
-  version: '0.1.0',
-  content: {
-    'example.html' => 'text/html',
-    'example.css' => 'text/css',
-    'example.js' => 'application/javascript'
-  },
-  data: {
-    'animals.yaml' => {
-      'animals' => [
-        { 'name' => 'Lion', 'type' => 'Mammal', 'habitat' => 'Savannah' },
-        { 'name' => 'Eagle', 'type' => 'Bird', 'habitat' => 'Mountains' },
-        { 'name' => 'Shark', 'type' => 'Fish', 'habitat' => 'Ocean' }
-      ]
-    }
-  },
-  metadata: {
-    'name' => 'sample_package',
-    'version' => '0.1.0',
-    'dependencies' => []
-  },
-  routes: {
-    '/' => 'example.html',
-    '/index' => 'index.html',
-    '/index.html' => 'index.html',
-    '/example.css' => 'example.css',
-    '/example.js' => 'example.js',
-    '/api/v1/data/animals' => { 'type' => 'dataset', 'name' => 'animals' }
-  },
-  storage: {
-    'datasets' => [
-      {
-        'name' => 'animals',
-        'source' => 'data/animals.yaml',
-        'format' => 'yaml',
-        'schema' => 'data/animals_schema.yaml'
-      }
-    ]
-  }
-)
+Secrets NEVER come from the package. They live in `deploy.json`
+(`--deploy` or `CAPSIUM_DEPLOY`):
 
-# Save the package to a file
-File.write('my_package.json', package.to_json(pretty: true))
+[source,json]
+----
+{
+  "baseUrl": "http://localhost:8864",
+  "authentication": {
+    "basicAuth": { "passwdFile": "/secure/outside/package/.htpasswd" },
+    "oauth2": { "clientSecret": "..." },
+    "sessionSecret": "...",
+    "roles": { "alice": ["admin"] }
+  }
+}
 ----
 
-=== Loading packages
+`roles` assigns roles by identity name (basic-auth username, OAuth2
+email or subject); userinfo `roles` claims are honored too. Without a
+configured `sessionSecret`, the reactor generates one and persists it
+(mode `0600`) outside the package.
 
-To load an existing package from a JSON file, you can use the `Capsium::Package.new(path)` method:
+== Programmatically managing packages
+
+The public API below ships with RBS signatures in `sig/`
+(`bundle exec rbs -I sig validate`).
+
+=== Loading packages
 
 [source,ruby]
 ----
 require 'capsium'
 
-# Read the package file or folder
+# Read a package directory or a .cap file
 package = Capsium::Package.new(path)
 
-# Inspect the loaded package
-puts package.inspect
+# Read an encrypted .cap (raises Capsium::Package::Cipher::KeyRequiredError
+# without a key, Capsium::Package::Cipher::DecryptionError for a wrong key
+# or tampered ciphertext)
+package = Capsium::Package.new('encrypted.cap', decryption_key: 'private.pem')
 ----
 
-=== Using packages in your program
+When `security.json` is present, the package is verified on load and
+`Capsium::Package::Security::IntegrityError` is raised on mismatch.
 
-Once you have created or loaded a package, you can use it within your Ruby application to access its content, data, and other properties.
+=== Using packages in your program
 
 [source,ruby]
 ----
 # Accessing package metadata
-puts "Package Name: #{package.metadata['name']}"
-puts "Package Version: #{package.metadata['version']}"
+puts "Package Name: #{package.metadata.name}"
+puts "Package Version: #{package.metadata.version}"
 
-# Accessing content
-package.content.each do |filename, content_type|
-  puts "Content File: #{filename}, Content Type: #{content_type}"
+# Accessing manifest resources
+package.manifest.resources.each do |path, resource|
+  puts "Resource: #{path}, Type: #{resource.type}"
 end
 
-# Accessing data
-animals_data = package.data['animals.yaml']
-puts "Animals Data: #{animals_data.inspect}"
-
 # Accessing routes
-package.routes.each do |route, destination|
-  puts "Route: #{route}, Destination: #{destination}"
+route = package.routes.resolve('/')
+puts route.resource
+
+# Accessing datasets
+animals = package.storage.dataset('animals')
+puts animals.data.inspect
+
+# Verifying integrity (returns a list of typed errors, empty when valid)
+errors = package.verify_integrity
+
+# Digital signatures (RSA-SHA256)
+package.signed?           # => security.json declares digitalSignatures
+package.verify_signature  # => true/false
+
+signer = Capsium::Package::Signer.new(package_dir)
+signer.sign('private.pem')                    # or sign('private.pem', 'cert.pem')
+signer.verify                                 # embedded public key
+signer.verify('cert-or-public-key.pem')       # explicit key
+signer.verify!                                # raises SignatureMismatchError
+
+# Whole-package encryption (AES-256-GCM, RSA-OAEP-SHA256 wrapped DEK)
+cipher = Capsium::Package::Cipher.new
+cipher.encrypt('pkg-1.0.0.cap', 'public.pem', 'encrypted.cap')
+cipher.decrypt('encrypted.cap', 'private.pem', 'decrypted.cap')
+Capsium::Package::Cipher.encrypted?('encrypted.cap')  # => true
+
+# Running the package's tests/*.yaml suite (05x-testing DSL)
+report = Capsium::Package::Testing::TestSuite.new(package).run
+report.ok?       # => true/false
+report.failures  # => failed TestCase::Result list
+report.summary   # => "7 tests, 0 failures"
+
+# Layered storage (5a): the merged overlay view shared with the reactor
+view = package.merged_view
+view.resolve('content/app.js')   # => absolute path of the topmost hit, or nil
+
+# Composite packages (4a): resolve metadata.dependencies against a store
+package = Capsium::Package.new(dir, store: './store')  # or CAPSIUM_STORE
+package.resolved_dependencies.each do |dep|
+  puts "#{dep.guid} (#{dep.range}) => #{dep.version} [#{dep.path}]"
 end
+view = package.merged_view                # own layers over dependency layers
+view = package.merged_view(exported_only: true)  # what dependents may see
 
-# Accessing storage definitions
-package.storage['datasets'].each do |dataset|
-  puts "Dataset Name: #{dataset['name']}, Source: #{dataset['source']}, Format: #{dataset['format']}"
-end
+# Serving with authentication and a store
+reactor = Capsium::Reactor.new(package: dir, store: './store',
+                              deploy: 'deploy.json')
+reactor.serve
+----
+
+=== Packing and unpacking programmatically
+
+[source,ruby]
+----
+packager = Capsium::Packager.new
+cap_file = packager.pack(package, force: true)
+packager.unpack(cap_file, 'output-directory')
+----
+
+== Building the mn-samples-iso cap package
+
+Download the mn-samples-iso built site: https://github.com/metanorma/mn-samples-iso/actions/runs/8862815829/artifacts/1453746303[mn-samples-iso-Linux].
+
+Then run these commands:
+
+[source,bash]
+----
+$ unzip mn-samples-iso-Linux.zip
+$ cd mn-samples-iso-Linux
+$ mkdir content
+$ mv index.html documents.xml documents content
+$ cat > metadata.json <<'JSON'
+{
+  "name": "mn-samples-iso",
+  "version": "0.1.0",
+  "description": "Metanorma ISO sample documents",
+  "guid": "https://github.com/metanorma/mn-samples-iso",
+  "uuid": "123e4567-e89b-12d3-a456-426614174000"
+}
+JSON
+$ cd ..
+$ bundle exec capsium package pack -f mn-samples-iso-Linux
+Package created: mn-samples-iso-0.1.0.cap
+$ bundle exec capsium reactor serve mn-samples-iso-0.1.0.cap
+Starting server on http://localhost:8864
+...
 ----
 
 == Contributing
@@ -247,7 +608,16 @@ To run the tests, use the following command:
 
 [source,bash]
 ----
-rspec
+bundle exec rspec
+----
+
+The linter and the RBS signature validation are part of the default rake
+task (`bundle exec rake`), or run them individually:
+
+[source,bash]
+----
+bundle exec rubocop
+bundle exec rbs -I sig validate
 ----
 
 == License
@@ -255,4 +625,3 @@ rspec
 Copyright Ribose.
 
 Capsium is released under the MIT License. See the LICENSE file for more details.
-