AI Reading Guide

Status: implemented navigation guide.

Use these routes to locate current authority before proposing or changing Sercrod work. They do not create an AI-only contract: implementation, canonical manual, detailed reference, sample, and tests remain authoritative.

First understanding Sercrod

Read first: What Sercrod Is, then Sercrod Core and The Runtime Flow.

For a Core change: follow Host and Scope, Data and Evaluation, Rendering Model, Actions and Results, and Updates and Redraw.

Then inspect: runtime specification (docs/spec/runtime.md) and canonical manual dist/man.json.

Source of truth: dist/sercrod.js and the applicable manual entry.

Required verification: trace each practical claim to detailed reference or test evidence.

Stop conditions: do not infer virtual-DOM ownership, Proxy- or MutationObserver-based scheduling, or a page-level framework boundary.

Changing a directive

Read first: AI Start Here (docs/spec/ai-start-here.md), AI runtime rules (docs/spec/ai-runtime-rules.md), and AI directives (docs/spec/ai-directives.md).

Then inspect: the exact dist/man.json entry, directive reference, dist/sercrod.js path, and focused test or sample.

Source of truth: current runtime and canonical manual.

Required verification: completion/checker evidence, focused behavior tests, and the relevant baseline when runtime behavior changes.

Stop conditions: a new directive/event/Core API, ambiguous ownership, changed result semantics, or contradictory current authorities.

Changing an adapter

Read first: Capabilities, Adapters, and Platforms and the public adapter reference.

Then inspect: its dist/adapters/ file, directive reference, architecture record, sample, manifest/lock, and focused tests.

Source of truth: adapter implementation, registration metadata, canonical manual, and tests.

Required verification: applicable owner/reference, redraw/removal, subscription-cleanup, controlled-call, safe-result, diagnostics, and sample evidence.

Stop conditions: a new namespace/permission, floating dependency, unsafe-result exception, destructive reconciliation, or general plugin system.

Changing a native backend

Read first: Samples and Packaging Boundaries and the public build-environment reference.

Then inspect: sandbox/app/<app>/app.json, shared www, selected src/platform/ entry, platform script, architecture sections, and build-contract tests.

Source of truth: capability contract, app manifest, exact lock, and platform-preparation ownership rules.

Required verification: platform selection/fallback, exact permissions/dependencies, managed-state refusal, and applicable build or simulation tests.

Stop conditions: Windows prerequisite installation without authorization, permission expansion, platform-specific HTML, forced backend uniformity, or overwriting generated native state.

Writing documentation

Read first: Inside Sercrod and the applicable conceptual page.

Then inspect: current runtime/manual/reference/test evidence for every material claim.

Source of truth: current implementation evidence, not historical roadmaps or a convenient older reference page.

Required verification: claim-level status, valid relative links, git diff --check, and reconciliation of version or authority mismatches.

Stop conditions: an unverified environment claim, contradictory current evidence, or wording that revises a settled public contract.

Changing a sample or packaging contract

Read first: Samples and Packaging Boundaries.

Then inspect: app.json, exact lock, shared www, platform entry, focused tests, and build scripts.

Source of truth: capability contract and sample manifest/lock ownership, not a generated native tree.

Required verification: exact dependency/permission checks, build-contract tests, and relevant runtime/adapter tests.

Stop conditions: a floating dependency, changed permission, manual generated-state repair, or release/publication without authorization.

Diagnosing lifecycle, error, or security behavior

Read first: Lifecycle, Ownership, and Security.

Then inspect: warnings and errors (docs/reference/warnings-and-errors.md), the relevant directive/adapter, diagnostics reference, and focused tests.

Source of truth: current cleanup, result-placement, diagnostics, and security behavior in implementation and tests.

Required verification: identify owner, trigger, result destination, cleanup path, and whether an environment boundary is real.

Stop conditions: exposing secrets or unsafe native objects, adding an error event, treating diagnostics as business policy, or masking failure as success.