@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/rmt-kernel-panic-recovery-incident-handoff.md

@@ -0,0 +1,60 @@
+# RMT Kernel Panic Recovery Incident Handoff
+
+- Contract: `xtend.rmt.kernel-migration-authoring-incident-handoff.v1`
+- Workpackage: `RKSH-WP-11`
+- Local gate: `node scripts/run_xtend_tests.js rmt-kernel-handoff-docs --json`
+
+This handoff describes how host teams evaluate panic and recovery diagnostics when the kernel trust layer blocks faulty outputs or starts recovery.
+
+## Diagnostics Channels
+
+| Channel | Purpose |
+|---------|---------|
+| `rmt.kernel.panic` | panic state, trigger, severity, scope and blocked commits |
+| `rmt.kernel.recovery` | recovery outcome, snapshot use, fallback and quarantine |
+| `rmt.kernel.escalation` | escalation envelope from diagnostics hub or command bus |
+| `rmt.kernel.scheduler_failure` | `failed`, `aborted`, `panic_blocked` and backpressure failure for jobs |
+
+## Minimum Fields for Incident Review
+
+- `panicId`
+- `correlationId`
+- `state`
+- `severity`
+- `scope`
+- `trigger`
+- `blockedCommitCount`
+- `recoveryAction`
+- `quarantined`
+- `hostNotified`
+- `affectedJobs`
+- `firstSeenAt`
+- `lastSeenAt`
+
+## Incident Severity
+
+| Severity | Meaning | Expected response |
+|----------|---------|-------------------|
+| `warning` | output was corrected or sanitized | observe verdicts, no escalation required |
+| `degraded` | output was blocked, UI remains usable with safe fallback | host team checks authoring or remote source |
+| `critical` | surface, template or binding was quarantined | open incident, track `correlationId` and `panicId` |
+| `fatal` | recovery failed or several kernel-scope errors correlate | stop release/traffic and restore last safe state |
+
+## Recovery Actions
+
+| `recoveryAction` | Meaning | Host handoff |
+|------------------|---------|--------------|
+| `rollback-last-safe-snapshot` | the kernel restores the last safe snapshot | preserve snapshot ID and surface scope |
+| `render-safe-fallback` | a checked fallback replaces unsafe output | check fallback markup and reason code |
+| `quarantine-surface` | affected surface accepts no new commits | disable remote source or adapter |
+| `abort-scope-jobs` | scheduler jobs in the affected scope are aborted | check `rmt.kernel.scheduler_failure` with `panic_blocked` |
+| `notify-host` | host adapter is actively informed about recovery | confirm `hostNotified` and host-log correlation |
+
+## Triage Flow
+
+1. Filter `rmt.kernel.panic` by `panicId`, `correlationId`, `scope`, `trigger` and `blockedCommitCount`.
+2. Connect `rmt.kernel.recovery` with the same `correlationId` and evaluate `recoveryAction`, `quarantined` and `hostNotified`.
+3. Check `rmt.kernel.escalation` if diagnostics subscribers or command handlers were involved.
+4. Check `rmt.kernel.scheduler_failure` if jobs are `failed`, `aborted` or `panic_blocked`.
+5. Correct authoring using [RMT Kernel Trusted Output Authoring](./rmt-kernel-trusted-output-authoring.md).
+6. Secure migration and regression with [RMT Kernel Security Hardening Migration](./rmt-kernel-security-hardening-migration.md) and `node scripts/run_xtend_tests.js rmt-kernel-security-regression --json`.

package/docs/en/rmt-kernel-security-hardening-migration.md

@@ -0,0 +1,49 @@
+# RMT Kernel Security Hardening Migration
+
+- Contract: `xtend.rmt.kernel-migration-authoring-incident-handoff.v1`
+- Workpackage: `RKSH-WP-11`
+- Status: `completed`
+- Local gate: `node scripts/run_xtend_tests.js rmt-kernel-handoff-docs --json`
+
+This document describes the migration for hosts and RMT authoring that previously used implicitly allowed runtime outputs. Since the kernel hardening, HTML, attributes, properties and remote outputs are committed only after the trust layer has produced an `RmtKernelRuntimeTrustVerdict`.
+
+## When a Trust Boundary Is Required
+
+| Output | Trust boundary | Migration |
+|--------|----------------|-----------|
+| `slot.html`, `prerender.html`, `fallback.html` | HTML must be evaluated before every DOM commit. | Use `commitTrustedHtml` with `sanitize html`, `html_fragment` and `safeFallbackHtml`. |
+| Direct DOM HTML sinks such as `innerHTML`, `insertAdjacentHTML` and `template.innerHTML` | These sinks remain privileged Trusted DOM sinks. | Remove direct writes and use the runtime trust-sink adapter. |
+| Attributes such as `href`, `src`, `srcset`, `action`, `formaction` and `srcdoc` | URL and sandbox policy decides before commit. | Use `commitTrustedAttribute` and block dangerous protocols such as `javascript:`. |
+| Event-close attributes such as `onclick`, `onload` or `onerror` | Event attributes are not allowed markup outputs. | Use commands or registered event handlers instead of HTML attributes. |
+| Style and DOM property writes such as `style`, `innerHTML`, `outerHTML`, `srcdoc` | Property policy evaluates side effects and DOM-clobbering risk. | Use `commitTrustedProperty` only for explicitly allowed properties. |
+| Remote outputs and adapter outputs | Remote surface boundaries need scope, origin, capability and integrity context. | Pass remote outputs as `remote-surface` or `adapter-output` scope into the trust authority. |
+
+## Replace Legacy Paths
+
+1. Remove direct HTML commits from components, adapters and host bridges. The kernel may reach `innerHTML`, `insertAdjacentHTML` or template HTML only through `commitTrustedHtml`.
+2. Mark HTML that should remain allowed as `html_fragment` and pass it through `sanitize html`. The sanitizer must remove or block `script`, `iframe`, `srcdoc`, `on*`, `javascript:` and comparable dangerous patterns.
+3. Write pure text as text: `textContent` is the preferred path for labels, status, error messages and user content.
+4. Separate attributes: `data-*` and `aria-*` remain normal structured attributes, while URL attributes go through `commitTrustedAttribute`.
+5. Separate properties: only explicitly allowed properties go through `commitTrustedProperty`; HTML-close properties remain blocked.
+6. Do not privilege fallbacks such as `fallback.html`. Recovery fallbacks must satisfy the same policy as normal outputs and must have `safeFallbackHtml`.
+7. Check diagnostics and regression: `listTrustVerdicts()`, `rmt.kernel.panic`, `rmt.kernel.recovery` and `node scripts/run_xtend_tests.js rmt-kernel-security-regression --json` must remain green after the migration.
+
+## SemVer Impact
+
+Blocked legacy outputs can be a breaking change if published hosts previously rendered intentionally unsafe markup and this behavior was part of the documented integration surface.
+
+| Change | SemVer |
+|--------|--------|
+| Unsafe HTML, URL or event attributes are newly blocked and existing apps can lose visible content because of that. | `major` |
+| Unsafe paths receive warnings, diagnostics or opt-in fallbacks, but previously safe output remains visible. | `minor` |
+| Only docs, tests, report fields or stricter diagnostics are added without output changes. | `patch` |
+
+Release notes for behavior-changing blocks must at least name the affected sinks, the reason code, the recovery path and the recommended migration.
+
+## Verification
+
+```bash
+node scripts/run_xtend_tests.js rmt-kernel-handoff-docs --json
+node scripts/run_xtend_tests.js rmt-kernel-security-regression --json
+node scripts/verify_xtendrmt_artifact_parity.js --json
+```

package/docs/en/rmt-kernel-trusted-output-authoring.md

@@ -0,0 +1,68 @@
+# RMT Kernel Trusted Output Authoring
+
+- Contract: `xtend.rmt.kernel-migration-authoring-incident-handoff.v1`
+- Workpackage: `RKSH-WP-11`
+- Package script: `npm run test:rmt-kernel-handoff-docs`
+
+RMT authoring must not assume a string is safe just because it comes from a template, remote surface or adapter. Every output-close authoring path needs a clear trust boundary and a safe fallback.
+
+## Authoring Rules
+
+- Text remains text: author labels, status, user content and error messages as `textContent` or structured text fields.
+- Author HTML only intentionally: use `html_fragment` with `sanitize html` and explicit scope.
+- Keep attributes small: `data-*` and `aria-*` are preferred; URL attributes go through `commitTrustedAttribute`.
+- Use properties only for allowed runtime targets: do not use DOM HTML properties as shortcuts.
+- Fallbacks are not privileged: `safeFallbackHtml` itself must be sanitizable and not interactively dangerous.
+- Remote surface outputs need scope, capability, origin and integrity context before they enter the kernel.
+
+## Safe Patterns
+
+```js
+runtime.commitTrustedHtml(slotTarget, {
+  scope: 'slot',
+  source: 'slot.html',
+  html: model.safeSummaryHtml,
+  policy: {
+    transform: 'sanitize html',
+    output: 'html_fragment'
+  },
+  safeFallbackHtml: '<p data-rmt-fallback="safe">Content unavailable.</p>'
+});
+```
+
+```js
+runtime.commitTrustedAttribute(linkTarget, {
+  scope: 'binding',
+  name: 'href',
+  value: model.href,
+  allowedProtocols: ['https:', 'mailto:']
+});
+```
+
+```js
+runtime.commitTrustedProperty(inputTarget, {
+  scope: 'binding',
+  name: 'value',
+  value: model.value,
+  policy: 'form-control-value'
+});
+```
+
+## Authoring Checklist
+
+| Question | Safe answer |
+|----------|-------------|
+| Does the output contain markup? | `html_fragment` plus `sanitize html` and `commitTrustedHtml`. |
+| Is it only text? | `textContent` or a structured text record. |
+| Is it a URL attribute? | `commitTrustedAttribute` with protocol allowlist. |
+| Is it `data-*` or `aria-*`? | Structured attribute commit, no HTML interpolation. |
+| Is it a fallback? | `safeFallbackHtml` with the same policy as normal HTML outputs. |
+| Does it come from remote or adapter code? | Trust scope `remote-surface` or `adapter-output`, capability and diagnostics correlation. |
+
+## No-Go Patterns
+
+- Forward markup from remote sources directly into `slot.html`, `prerender.html` or `fallback.html`.
+- Transport event attributes such as `onclick` as data.
+- Use `style` or HTML-close properties as an escape hatch.
+- Build `safeFallbackHtml` from the same unsafe source as the blocked output.
+- Ignore diagnostics when a verdict reports `blocked` or `panic`.

package/docs/en/rmt-language-server.md

@@ -0,0 +1,243 @@
+# RMT Language Server and Editor Setup
+
+- Status: productively prepared since `WP-E14-14`
+- Contract: `xtend.rmt.editor-packaging.v1`
+- Language Server: `xtend.rmt.language-server.v1`
+- Snippet Catalog: `xtend.rmt.snippet-catalog.v1`
+- Epic 14 Handoff: `xtend.epic14.lsp-handoff.v1`
+- Primary file type: `.rmt`
+- Local gates:
+  - `node scripts/run_xtend_tests.js rmt-editor-packaging --json`
+  - `node scripts/run_xtend_tests.js rmt-tooling-docs --json`
+  - `node scripts/run_xtend_tests.js epic14-lsp-handoff --json`
+
+## Goal
+
+RMT tooling is editor-agnostic. The domain source of truth lives in:
+
+- `tools/rmt-language`
+- `tools/rmt-linter`
+- `tools/rmt-language-server`
+
+Editor packages may provide snippets, syntax highlighting, and launch commands
+for the LSP. They must not implement a second RMT semantics layer.
+
+## Start the Language Server
+
+The server speaks stdio JSON-RPC:
+
+```bash
+node tools/rmt-language-server/server.js
+```
+
+The server currently provides:
+
+- Diagnostics
+- Completion
+- Hover
+- Document Symbols
+- Definition
+- Code Actions
+
+The LSP uses the same diagnostic core as `xt rmt lint`. Editor integrations
+should therefore not maintain their own RMT rules.
+
+## LSP Capability Matrix
+
+| Capability | Protocol / Surface | Status | Source of Truth | Gate |
+|------------|--------------------|--------|-----------------|------|
+| Diagnostics | `textDocument/publishDiagnostics` | implemented | `xtend.rmt.linter.rule-engine.v1` | `rmt-linter-rules` |
+| Completion | `textDocument/completion` | implemented | `xtend.rmt.completion-provider.v1` | `rmt-completions` |
+| Hover | `textDocument/hover` | implemented | `xtend.rmt.hover-provider.v1` | `rmt-navigation` |
+| Document Symbols | `textDocument/documentSymbol` | implemented | `xtend.rmt.document-symbols-provider.v1` | `rmt-navigation` |
+| Definition | `textDocument/definition` | implemented | `xtend.rmt.definition-provider.v1` | `rmt-navigation` |
+| Code Actions | `textDocument/codeAction` | implemented | `xtend.rmt.code-action-provider.v1` | `rmt-code-actions` |
+| Agent Repair Report | `xt rmt lint --agent` | implemented | `xtend.rmt.ai-agent-repair-report.v1` | `rmt-agent-report` |
+| Snippets | Editor Packaging | implemented | `xtend.rmt.snippet-catalog.v1` | `rmt-editor-packaging` |
+| Workspace Symbols | `workspace/symbol` | planned | Project Index follow-up | future |
+| Rename | `textDocument/rename` | planned | Safe Refactor follow-up | future |
+| References | `textDocument/references` | planned | Project Index follow-up | future |
+| Semantic Tokens | `textDocument/semanticTokens` | planned | Syntax Highlighting follow-up | future |
+| Formatting | `textDocument/formatting` | planned | Formatter follow-up | future |
+
+## Known Limitations
+
+- The current authoring MVP is still JSON-based. A friendlier DSL syntax is
+  follow-up work.
+- `textDocument/formatting` is planned but not productively released.
+- `workspace/symbol`, `textDocument/rename`, and `textDocument/references`
+  need a project-wide index and intentionally remain outside the MVP.
+- Marketplace packaging for individual editors is not part of Epic 14. The
+  generic LSP setup remains the current integration path.
+- The Language Server does not execute XTend components, start XRouter, or
+  materialize DOM.
+- `.rmt.json` remains readable, but is treated as a fallback and should not be
+  the normal path in new projects.
+
+## Snippets
+
+The editor-agnostic snippet catalog lives in:
+
+```text
+tools/rmt-language/snippets/index.js
+```
+
+The VS Code-compatible export format lives in:
+
+```text
+tools/rmt-language/snippets/rmt.code-snippets
+```
+
+All snippets create native `.rmt` authoring structures. `.rmt.json` remains
+only a parser/linter fallback and should not be used in new snippets.
+
+Important prefixes:
+
+| Prefix | Purpose |
+|--------|---------|
+| `rmt-app` | minimal native app shell |
+| `rmt-component` | XTend component record |
+| `rmt-route` | XRouter route record |
+| `rmt-schedule` | schedule policy |
+| `rmt-template-dom` | safe `dom_descriptor` template |
+| `rmt-template-html` | `html_fragment` with Trusted DOM boundary |
+
+## VS Code
+
+The VS Code integration lives in:
+
+```text
+tools/rmt-editor/vscode
+```
+
+It registers:
+
+- Language ID `rmt`
+- File extension `.rmt`
+- RMT vNext-aware TextMate grammar with a legacy JSON fallback
+- RMT snippets
+- `vscode-languageclient` for the local RMT Language Server
+- `$xtend-rmt-lint` problem matcher
+- XTend CLI tasks and Debug Console launch configurations
+- Command `XTendRMT: Show Language Server Command`
+- Command `XTendRMT: Start/Restart Language Server`
+- Command `XTendRMT: Run Active RMT Lint`
+- Command `XTendRMT: Run Workspace RMT Lint`
+- Command `XTendRMT: Run RMT Build Check`
+- Command `XTendRMT: Run Scaffold Verify`
+- Command `XTendRMT: Debug Language Server`
+- Command `XTendRMT: Debug Active RMT Lint`
+- Command `XTendRMT: Debug Active RMT Build`
+- Command `XTendRMT: Open XTend CLI Terminal`
+- Command `XTendRMT: Run XTend CLI Command...`
+- Command `XTendRMT: Run Agent Repair Report`
+- Command `XTendRMT: Run RMT Build Write`
+- Command `XTendRMT: Open VS Code Tasks Template`
+- Command `XTendRMT: Open VS Code Launch Template`
+- Command `XTendRMT: Show vNext Primitive Apply Experience`
+- Command `XTendRMT: Show vNext Primitive Code Action Preview`
+- Command `XTendRMT: Show vNext Primitive Command Handoff`
+
+The packaged LanguageClient starts the server through stdio:
+
+```json
+{
+  "command": "node",
+  "args": ["tools/rmt-language-server/server.js"]
+}
+```
+
+Terminal tasks use the XTend CLI as their orchestrator and do not maintain a
+second RMT semantics layer. The extension resolves the CLI from the workspace
+first at `xtend-builder/scaffold.js`, then `node_modules/.bin/xt`, and then
+`node_modules/@ccslabs/xtend-cli/scaffold.js`. If a project uses another
+layout, `xtendRmt.xtendCli.path` can point to an executable or `scaffold.js`.
+The versioned template lives at:
+
+```text
+tools/rmt-editor/vscode/templates/tasks.json
+```
+
+The problem matcher consumes the stable linter output:
+
+```bash
+xt rmt lint app.rmt --format problem-matcher --fail-on warning
+```
+
+The Debug Console launch template lives at:
+
+```text
+tools/rmt-editor/vscode/templates/launch.json
+```
+
+It contains debug starts for the Language Server, active RMT lint, active RMT
+build and scaffold verify. This is tool debugging for authoring workflows; a
+custom debug adapter for runtime RMT UI breakpoints remains outside this slice.
+
+The vNext primitive commands read CodeAction reports or individual actions from
+the RMT vNext tooling layer and show the three apply paths separately in the
+Output Channel:
+
+- safe individual quick fixes;
+- `source.fixAll.rmt.vnext.primitives` for all safe WorkspaceEdits;
+- manual `xtend.rmt.vnext.extractKernelImport` handoffs for Kernel/Fabric
+  boundary violations without an automatic WorkspaceEdit.
+
+## JetBrains
+
+JetBrains IDEs can be connected through a generic LSP client or a local file
+watcher/external tool setup.
+
+Recommended values:
+
+- Language ID: `rmt`
+- Extension: `.rmt`
+- Command: `node`
+- Args: `tools/rmt-language-server/server.js`
+
+## Neovim
+
+Minimal `nvim-lspconfig`-compatible starting point:
+
+```lua
+local lspconfig = require('lspconfig')
+local configs = require('lspconfig.configs')
+
+configs.xtendrmt = {
+  default_config = {
+    cmd = { 'node', 'tools/rmt-language-server/server.js' },
+    filetypes = { 'rmt' },
+    root_dir = lspconfig.util.root_pattern('package.json', '.git')
+  }
+}
+
+lspconfig.xtendrmt.setup({})
+```
+
+## Helix
+
+Example for `languages.toml`:
+
+```toml
+[[language]]
+name = "rmt"
+scope = "source.rmt"
+file-types = ["rmt"]
+language-servers = ["xtendrmt"]
+
+[language-server.xtendrmt]
+command = "node"
+args = ["tools/rmt-language-server/server.js"]
+```
+
+## Boundary
+
+Editor packaging must not execute XTend components, start XRouter, or create
+DOM side effects. It only starts the LSP and provides static snippets.
+
+## Related Guides
+
+- [RMT Linter and AI-Agent Repair Report](./rmt-linter.md)
+- [XTendRMT Native Authoring Guide](./xtendrmt-native-authoring.md)
+- [Quick Start Guide](./quick-start-guide.md)
+- [Epic 14 Completion and LSP Handoff](../development/XTendRMT-Epic14-Abschluss-und-LSP-Handoff.md)

package/docs/en/rmt-lifecycle-demo.md

@@ -0,0 +1,23 @@
+# RMT Lifecycle Demo
+
+Contract: `xtend.rmt.lifecycle-demo.v1`
+
+The lifecycle demo shows the complete path from RMT authoring to an openable XTend app:
+
+1. `xtendrmt/rmt-lifecycle-demo.rmt` is the RMT vNext template.
+2. `node xtend-builder/scaffold.js rmt-lifecycle-demo --write --json` compiles
+   the template into `xtendrmt/rmt-lifecycle-demo.core.json`.
+3. The same scaffold build writes the generated artifacts:
+   `components/x-rmt-lifecycle-demo.js`,
+   `xtendrmt/rmt-lifecycle-demo.app.js`,
+   `tests/browser/fixtures/rmt-lifecycle-demo-smoke.html`.
+4. The app can be opened through the local HTTP server:
+   `node scripts/serve_xtend_dev.js --default tests/browser/fixtures/rmt-lifecycle-demo-smoke.html`.
+
+The build report is stored at `xtendrmt/rmt-lifecycle-demo.scaffold.json`. It
+connects source, core output, generated XTend app, browser smoke and the local
+gate `node scripts/run_xtend_tests.js rmt-lifecycle-demo --json`.
+
+The generated files are intentionally marked with `@generated by XTend Scaffold RMT
+lifecycle build`. Changes should be made in the vNext template or scaffold
+generator, not directly in the generated artifacts.

package/docs/en/rmt-linter.md

@@ -0,0 +1,146 @@
+# RMT Linter and AI-Agent Repair Report
+
+- Status: productively prepared since `WP-E14-14`
+- Contract: `xtend.rmt.tooling-docs.v1`
+- Linter Report: `xtend.rmt.linter.report.v1`
+- Agent Report: `xtend.rmt.ai-agent-repair-report.v1`
+- Primary file type: `.rmt`
+- Local gate: `node scripts/run_xtend_tests.js rmt-tooling-docs --json`
+
+## Purpose
+
+The RMT Linter makes native `.rmt` documents verifiable locally, in CI, and for
+AI agents. It uses the same language layer as the RMT Language Server:
+
+- Source Model
+- Parser and Format Adapter
+- Semantic Graph
+- Linter Rules
+- Code Actions
+- Agent Repair Report
+
+The linter does not execute XTend components, start XRouter, or materialize DOM.
+It analyzes RMT as a language.
+
+## Default Command
+
+```bash
+xt rmt lint app.rmt
+```
+
+The long command path remains valid as well:
+
+```bash
+xtend rmt lint app.rmt
+```
+
+Directory targets and simple glob targets are supported:
+
+```bash
+xt rmt lint tests/rmt-language/fixtures
+xt rmt lint "tests/rmt-language/fixtures/*.rmt" --json
+```
+
+## JSON Report
+
+```bash
+xt rmt lint app.rmt --json
+```
+
+The report is intended for CI and other tools:
+
+```json
+{
+  "schema": "xtend.rmt.linter.report.v1",
+  "status": "failed",
+  "files": 1,
+  "diagnostics": []
+}
+```
+
+## Fail Policy
+
+The default is `--fail-on error`. Warnings do not break the local run in that
+mode.
+
+```bash
+xt rmt lint app.rmt --fail-on warning
+xt rmt lint app.rmt --fail-on info
+```
+
+CI can therefore run stricter checks than local authoring loops.
+
+## Agent Report
+
+AI agents use the repair report:
+
+```bash
+xt rmt lint app.rmt --agent
+```
+
+`--agent` implies JSON and returns:
+
+- `diagnostics`
+- `repairPlan`
+- `fixOrder`
+- `noOps`
+- `confidence`
+- `impact`
+- `relatedDiagnostics`
+
+Diagnostics that cannot be safely automated are intentionally explained as
+no-ops. Examples include syntax recovery, inline-script removal, or component
+stubs that need authoring context.
+
+## Diagnostic Codes
+
+Important codes:
+
+| Code | Meaning |
+|------|---------|
+| `rmt.syntax.invalid-json` | the document cannot be parsed syntactically |
+| `rmt.document.extension.fallback-used` | `.rmt.json` or `.json` is used only as a fallback |
+| `rmt.document.kind.missing` | `kind: "rmt_document"` is missing |
+| `rmt.adapter.unknown` | adapter reference is not defined |
+| `rmt.ref.component.unresolved` | component reference cannot be resolved |
+| `rmt.ref.template.unresolved` | template reference cannot be resolved |
+| `rmt.ref.schedule.unresolved` | schedule reference cannot be resolved |
+| `rmt.ref.route.duplicate-path` | route path is defined more than once |
+| `rmt.fabric.lane.unknown` | Fabric/RMT lane is unknown |
+| `rmt.template.inline-script.refused` | inline script violates the Trusted DOM/kernel boundary |
+
+## Quick Fixes
+
+Safe repairs come from `xtend.rmt.code-action-provider.v1`.
+
+The MVP supports:
+
+- creating missing schedules
+- creating missing templates as `dom_descriptor` stubs
+- changing unknown Fabric lanes to `visible`
+- changing unknown hydration policies to `runtime_render`
+- adding missing route `documentTitle`
+- adding missing schedule `endpointName`
+- renaming `.rmt.json` to `.rmt` via command
+
+## Regression Gate
+
+The tooling matrix lives in:
+
+```bash
+node scripts/run_xtend_tests.js rmt-language-regression --json
+```
+
+This gate checks valid, broken, legacy, and larger RMT documents across parser,
+linter, CLI, LSP, and agent report.
+
+## Editor Workflow
+
+For IDEs, see [RMT Language Server and Editor Setup](./rmt-language-server.md).
+
+Recommended flow:
+
+1. Create a new document with the `rmt-app` snippet.
+2. Use diagnostics and completion in the IDE.
+3. Check locally with `xt rmt lint app.rmt`.
+4. Use `xt rmt lint app.rmt --agent` for agents or CI.

package/docs/en/rmt-node-ssr-adapter.md

@@ -0,0 +1,99 @@
+# RMT Node SSR Adapter
+
+The Node SSR Adapter is the lightweight server-side API for XTendRMT. It emits
+Light DOM HTML for XTend Custom Elements, RenderMan-compatible hydration
+payloads, and optional JSONL streaming for incremental UI components.
+
+Schema: `xtend.rmt.node-ssr-adapter.v1`
+
+```js
+import {
+  createRmtNodeSsrAdapter
+} from '@ccslabs/xtend/rmt/node-ssr-adapter';
+```
+
+The runtime package exposes the same API via
+`@ccslabs/xtend-rmt/node-ssr-adapter`.
+
+For PHP/Laravel hosts, the
+[RMT PHP/Laravel SSR Adapter](./rmt-php-ssr-adapter.md) provides the same
+client wire contract: HTML, hydration, RenderMan chunks, and JSONL frames stay
+compatible.
+
+## Architecture
+
+The adapter is a host layer, not a second renderer. RMT vNext describes source,
+state, selectors, actions, events, surfaces, and streams. The compiler emits
+Core and Kernel records. The Component Capability Registry describes XTend UI
+generically. The Node adapter serializes that into safe server-side startup
+output.
+
+It does not instantiate Custom Elements on the server, does not access private
+component internals, does not start an HTTP server, and does not perform
+implicit global network calls.
+
+## API
+
+```js
+const adapter = createRmtNodeSsrAdapter({
+  manifest,
+  sourceTexts,
+  endpointHandlers: {
+    'ssr.hero': () => ({
+      html: '<x-hero>Hero</x-hero>',
+      trustBoundary: 'xtend.security.sanitizing-boundary.v1'
+    })
+  }
+});
+
+const result = await adapter.render({
+  source,
+  filePath: 'app.rmt'
+});
+```
+
+`render` accepts RMT source, Core Documents, Prepared Templates, and DOM
+Descriptors. In the full package, source compilation is wired through the
+existing vNext compiler. Runtime-only hosts inject `compileRmtVNextSource`; if
+that function is missing, the adapter reports `rmt.node_ssr.compiler_required`.
+
+## Output
+
+`xtend.rmt.node-ssr-render-result.v1` contains:
+
+- `html`
+- `head.preloads`
+- `renderman_template_chunk`
+- `server_prerender_hydrate` hydration data
+- `xtend.rmt.vnext-streaming-contract.v1`
+- Component Capability markers
+- diagnostics
+
+## JSONL Streaming
+
+`streamJsonl` yields frames with
+`xtend.rmt.node-ssr-jsonl-frame.v1`. Important frame types are `start`,
+`component`, `html`, `hydration`, `diagnostic`, `complete`, and `error`.
+
+The streaming capabilities stay compatible with RMT vNext:
+
+- `stream.ssr.incremental`
+- `stream.hydration.chunked`
+
+## Data Sources and Security
+
+Data sources are resolved only through explicit host hooks:
+`resolveDataSource`, `endpointHandlers`, `staticDataSources`, `fixtures`, or
+`fetchAdapter`. Missing resolvers report `rmt.node_ssr.datasource_missing`.
+
+HTML fragments need a trust boundary such as
+`xtend.security.sanitizing-boundary.v1` or
+`xtend.security.streaming-boundary.v1`. Unsafe URLs, event attributes, `srcdoc`,
+and blocked tags are diagnosed and cleaned.
+
+## Gate
+
+```bash
+npm run test:rmt-node-ssr-adapter
+node scripts/run_xtend_tests.js rmt-node-ssr-adapter --json
+```