docs: reconcile Uhura 0.4 documentation and the uhura-lang skill

[softmarshmallow]

Status

Actionable documentation and public-skill maintenance. This issue does not select new language semantics or declare a supported compatibility version.

Context

Uhura PR #24 replaced the executable 0.3 frontend with the machine-first Uhura 0.4 incubation candidate. Spock PR #26 then aligned the framework integration and the public uhura-lang skill with that replacement.

Uhura PR #26 subsequently made the 0.4 frontend canonical internally and implemented the first checked source-annotation/authoring-metadata slice. The language docs and public skill now need a deliberate post-rewrite reconciliation pass.

There is already one confirmed contradiction:

• docs/spec/README.md still says RFC 0003 attachment and the authoring projection are pending as a whole.
• docs/rfcs/0003-source-comments-docs-and-annotations.md and docs/spec/drafts/0.4/source.md correctly record the implemented subset and the remaining work.

The current public skill also predates that annotation work: it has no source-comment/annotation guidance, describes Editor only as an evidence projection, and has no annotation-only authoring or verification path.

Goal

Make the living Uhura documentation and the installable uhura-lang skill describe one accurate, executable 0.4 contract, while keeping Uhura's versioned specification as the authority and the skill as a concise operational guide.

Reconciliation scope

1. Reconcile canonical Uhura documentation

• Audit the living routers, 0.4 owner documents, RFC status, implementation map, checked UI catalogue, and canonical examples against the current frontend and tests.
• Fix the RFC 0003 status contradiction in the specification router.
• Add the compiler-owned authoring sidecar and Editor annotation projection where the application, project/provenance, and implementation documents currently describe semantic provenance alone.
• State the implemented annotation boundary precisely: ordinary XML-shaped markup comments and <!-- @lower-kebab-kind ... --> annotations in UI sibling lists; deterministic forward attachment to supported native elements or complete if/each blocks; structured malformed, dangling, and incompatible-target diagnostics; and authoring metadata that does not enter machine or presentation identity.
• State the remaining RFC 0003 work just as precisely: DSL ordinary-comment attachment/formatting, declaration/file docs, and the exact non-sibling placement gate remain pending. Do not imply full RFC implementation.
• Preserve the distinction between canonical unversioned internal frontend names and intentional external language = "0.4", wire, catalogue, specification, and harness identities.

2. Reconcile the public uhura-lang skill

Update the relevant files under gridaco/spock/skills/uhura-lang, including SKILL.md, references/*, and agents/openai.yaml when its trigger/default prompt needs to change.

The skill should:

• cover source comments, annotations, attachment targets, diagnostics, semantic inertness, and metadata preservation without teaching unimplemented declaration-doc behavior;
• distinguish the checked evidence projection from the separate compiler-owned authoring projection while preserving Editor's read-only and non-runtime-proof boundaries;
• add an annotation-only modification and verification workflow: project check, Editor target/card/source navigation, and confirmation that runtime/provider behavior and semantic identities are unchanged;
• retain the machine/UI/evidence/host/provider ownership boundaries already aligned in Spock PR Expose source annotations and canonicalize the frontend #26;
• recheck version-specific npm compatibility wording against the actual published spock distribution at implementation time, preserving the public-distribution gate and the public-vs-contributor workflow boundary; and
• link back to the versioned Uhura authorities instead of becoming a second unversioned living specification.

3. Audit for broader post-rewrite drift

Search both surfaces for stale guidance around .relay, .examples.uhura, retired page/component/store syntax, per-file language or module headers, fixture-script execution, compatibility loaders, the removed Uhura dev alias, and internal v04/v0.4/0_4 implementation names. Historical and intentional external 0.4 references must remain clearly classified rather than removed mechanically.

Acceptance criteria

• No living Uhura router or guide contradicts the implemented/remaining RFC 0003 boundary.
• The uhura-lang skill explicitly teaches the supported annotation workflow and its current limits.
• Every snippet presented as runnable is checked as a complete manifest-resolved 0.4 project; illustrative fragments are labeled as such.
• The canonical L0-L2, A0, and Instagram 0.4 projects still pass uhura check --deny-warnings.
• Annotation parser/formatter and checked-authoring-sidecar tests cover the documented positive and negative forms.
• The public skill passes the same canonical skill validation used by Spock PR Expose source annotations and canonicalize the frontend #26, and its install/discovery surface still exposes uhura-lang correctly.
• Uhura and Spock companion PRs cross-link each other and identify which corrected Uhura revision the skill mirrors.

Non-goals

• changing the 0.4 kernel, grammar, runtime, or compatibility policy;
• implementing the remaining RFC 0003 phases as part of a docs/skill patch;
• reviving any retired 0.3/v0 admission path;
• turning the skill into the canonical language specification; or
• baking unresolved studies or proposals such as #27 or #31 into current language guidance before they are accepted and implemented.