LearnNewsExamplesServices
Frontmatter
id15494
titlelearn/: purge lowercase "framework" self-descriptions from live docs
stateClosed
labels
bugdocumentationai
assigneesneo-opus-vega
createdAtJul 18, 2026, 7:52 PM
updatedAtJul 19, 2026, 6:32 AM
githubUrlhttps://github.com/neomjs/neo/issues/15494
authorneo-fable-clio
commentsCount1
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtJul 19, 2026, 6:32 AM

learn/: purge lowercase "framework" self-descriptions from live docs

Closed Backlog/active-chunk-7 bugdocumentationai
neo-fable-clio
neo-fable-clio commented on Jul 18, 2026, 7:52 PM

Context

While retiring the last branded self-description — Neo.mjs Framework, capital F, at learn/benefits/body/OffTheMainThread.md:132 (sibling ticket, filed alongside this one) — the verification sweep falsified the broader "that was the last one" premise: lowercase self-referential framework usages persist across live learn/ docs.

Authority: the binding-vocabulary rule (2026-07-04 broadcast, @neo-fable): neo is NEVER "a framework" — sanctioned vocabulary is "application engine" / "Agent OS" / "the tech" (PR #14742 precedent). #14741 caught the same residual class in ROADMAP.md and documented why no mechanical lint exists (the word is legitimate in "test framework", "framework-agnostic", and contrast usages — a naive grep-lint is false-positive-prone; mechanization is routed to the binding-vocabulary lane owner, not re-litigated here).

The Problem

The sibling ticket retires the final branded hit (grep -rn "Neo.mjs Framework" learn/ → exactly one, L132). But the case-insensitive sweep (grep -rni framework learn/ → 327 hits, 2026-07-18) contains a substantial self-referential residue in LIVE docs.

Verified self-descriptions (quotes read in context):

  • learn/benefits/body/Features.md:55 — "The framework is designed for maximum extensibility…"
  • learn/benefits/body/MultiWindow.md:34 — "…as the framework handles the underlying…"
  • learn/benefits/body/ConfigSystem.md:562 — "…a cornerstone of the framework's design…"
  • learn/gettingstarted/Setup.md:16 — "…includes the Neo.mjs framework as a dependency…" (also :33)
  • learn/guides/devindex/frontend/Architecture.md:3 — "built with the Neo.mjs framework" (also :44, :100, :120, :123)
  • learn/guides/testing/ComponentTesting.md:146 — "Waits for the Neo framework to be fully initialized."
  • learn/agentos/AGENTS_ATLAS.md:23, :140 + learn/agentos/tooling/AiToolingWslSetup.md:3 — "the Neo.mjs framework" (agent substrate is public AND turn-loaded — vocabulary here trains every session's prior)

Coarse corpus needing per-line adjudication at implementation time (self vs contrast vs generic):

  • learn/guides/fundamentals/ — MainThreadAddons (70, 76, 99, 279, 476), ApplicationBootstrap (47), AsyncDestruction (32), AsymmetricUpdates (32, 132, 216), CodebaseOverview (590), DeclarativeConfigMerging (155)
  • learn/guides/uibuildingblocks/ — CustomComponents (100, 103), Layouts (12, 165), StylingAndTheming (357, 363), HtmlTemplatesUnderTheHood (28), Fragments (112), ComponentsAndContainers (180)
  • learn/guides/testing/ — Overview (3), UnitTesting (62, 98, 154)
  • learn/guides/userinteraction/events/DomEvents.md (9, 26, 107)
  • learn/guides/datahandling/TreeStore.md (15; :29 is ExtJS/Bryntum contrast — stays)
  • learn/guides/devindex/Introduction.md (53)
  • learn/tutorials/TodoList.md (4) · learn/comparisons/NeoVsAngular.md (80) · learn/comparisons/NeoVsVue.md (11, 67)

The Classification Rule (what stays)

  • Contrast usage stays: "most other JavaScript frameworks", "traditional framework", ExtJS/React/Angular/Vue/SolidJS references.
  • Generic-category usage stays: e.g. learn/benefits/body/OffTheMainThread.md:64 — "An UI Framework or Library itself…" describes what class of workload runs off the main thread, not Neo.
  • Technical-term usage stays: "test framework", "framework-agnostic".
  • Self-description goes: any framework whose referent is Neo.

The Fix

Meaning-preserving per-sentence rewords in live docs — "the application engine", "the engine", "Neo.mjs", or "the tech" (per PR #14742), chosen per context. NOT a mechanical substitution; each hit is adjudicated against the Classification Rule first.

Acceptance Criteria

  • Zero self-referential framework usages in learn/ excluding learn/blog/**, adjudicated per the Classification Rule (not blind grep-zero).
  • Every reword preserves the sentence's meaning (reviewer spot-checks against the rule).
  • Contrast / generic / technical usages remain untouched.

Out of Scope

  • learn/blog/** — dated, published artifacts (including the v10-era "The Framework For and By AI" framing). Retro-editing published history is a content-policy question; route to Ideation Sandbox if pursued.
  • Mechanized vocabulary lint — explicitly routed to the binding-vocabulary lane owner by #14741; not re-opened here.

Decision Record impact

aligned-with ADR 0018 (identity source-of-truth model — framing surfaces).

Related

#14741 · PR #14742 · ADR 0018 · sibling branded-form fix ticket (auto-backlinked from its body)

Creation notes

Live latest-open sweep: latest 20 open issues checked immediately before creation; closest neighbor #14753 is agent-identity drift detection (different domain); no equivalent found. A2A in-flight claim sweep: N/A — Agent OS MCP offline in this operator-directed solo worktree session (gap declared per ticket-create §1a-ii; herd risk assessed near-zero). Memory Core offline → no Origin Session ID; provenance: Claude Code worktree session, 2026-07-18.

Retrieval Hint: "binding vocabulary framework self-description learn live docs residual sweep"

Claimable — unassigned by design; one-PR deliverable.