Skip to content

Docs: add plain Wesley onboarding path #678

Description

@flyingrobots

Problem

The README quick start is usable, but deeper docs still require too much internal vocabulary before a new GraphQL/Rust contributor can understand the product surface.

Evidence at e948217274fe:

  • README.md:40 has a normal quick start.
  • README.md:56 shows schema lower and emit commands.
  • README.md:118 introduces external module examples.
  • docs/GUIDE.md:148 foregrounds HOLMES / Watson / Moriarty / BLADE.
  • docs/GUIDE.md:171 introduces Realization Shells and Witness Surfaces.
  • docs/WESLEY_GLOSSARY.md:168 defines the assurance vocabulary.

The vocabulary is useful internally, but it is a tax on first-hour adoption.

Mitigation Plan

  • Create a Plain Wesley docs track: GraphQL in, deterministic JSON IR out, optional Rust/TypeScript/codec emitters, external target owns meaning.
  • Move toolchain/mythology terms behind an advanced assurance vocabulary page.
  • Add a standard GraphQL-to-Wesley term map: SDL, type, field, directive, operation, schema hash, L1 IR, emitter.
  • Add one beginner tutorial: install CLI, lower a schema, inspect IR, emit Rust, emit TypeScript, validate manifest.
  • Add one contributor tutorial: add a simple generic emitter field behavior with test-first workflow.
  • Add a docs/release rule: new public nouns need a plain-English alias or must be marked internal/experimental.

Acceptance Criteria

  • A new user can complete the first tutorial without reading the glossary.
  • The guide clearly separates compiler basics from advanced assurance/toolchain vocabulary.
  • Docs-check/preflight cover any new routed docs pages.

Activity

  1. added
    legend:DXDeveloper experience work
    legend:DOCSDocumentation truth work
    triage:requestsUnscheduled valid requests that still need a release scheduling decision
    on Jul 4, 2026
  2. coderabbitai commented on Jul 4, 2026

    @coderabbitai
    🔗 Related PRs

    #45 - docs(qir): document lowering + emission (MVP) [merged]
    #475 - Merge-worthy unmerged branches into omnibus reconciliation branch [merged]
    #503 - Revise README.md for clarity and additional information [merged]
    #504 - Compile runtime optic artifacts [merged]
    #506 - chore(release): v0.0.3 [merged]


    📝 Issue Planner

    Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.

    • Create Plan

    🧪 Issue enrichment is currently in open beta.

    You can configure auto-planning by selecting labels in the issue_enrichment configuration.

    To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

    issue_enrichment:
      auto_enrich:
        enabled: false

    💬 Have feedback or questions? Drop into our discord!

  3. added
    docsDocumentation changes
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    status: non-blockingThis issue is not a blocker for a release.
    on Jul 4, 2026
  4. flyingrobots commented on Jul 5, 2026

    @flyingrobots
    OwnerAuthor

    Closing as completed by PR #686, which added the Plain Wesley onboarding path and first-hour docs. The stacked work landed on main through PR #685.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation changesdocumentationImprovements or additions to documentationenhancementNew feature or requestlegend:DOCSDocumentation truth worklegend:DXDeveloper experience workstatus: non-blockingThis issue is not a blocker for a release.triage:requestsUnscheduled valid requests that still need a release scheduling decisionwork-in-progressMethod issue is actively being worked

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions