Skip to content

Source status: no status is stated in the source document, so none is assigned here. Do not treat this page as a finalized specification. The normative rules are in the Technical Specification.

Documentation and Language Discoverability

The language will provide structured, authoritative documentation designed for both human developers and AI agents.

1. Language Specification

  • A complete, versioned language specification must be maintained.
  • Every syntax rule must have a precise definition.
  • Type behavior and compiler semantics must be documented.
  • Contracts and verification rules must be formally described.
  • Ambiguous or undocumented behavior must not be permitted.

2. Machine-Readable Documentation

  • Language definitions must be available in structured formats.
  • Types, functions, parameters, return values, and effects must be discoverable.
  • Compiler diagnostics must reference relevant specification rules.
  • AI agents must be able to query available language features and APIs.

3. Documentation Integrity

  • Documentation must correspond to a specific language version.
  • Outdated documentation must be identifiable.
  • Standard library documentation must be generated from authoritative definitions where possible.
  • Examples must be compilable and tested.
  • Documentation changes must trigger relevant validation.

4. AI Agent Discovery

The compiler and development tools should expose: - Available syntax and language constructs. - Type definitions and constraints. - Function contracts. - Permissions and side effects. - Dependency interfaces. - Verification capabilities and limitations. - Relevant examples and diagnostic explanations.

5. Version Compatibility

  • Agents must be able to identify the language version of a project.
  • Documentation queries must respect that version.
  • Deprecated features must be clearly identified.
  • Breaking language changes must be documented.

Design Goal

An AI agent should be able to discover the exact rules and capabilities of the language at development time instead of guessing based on potentially outdated training data.

Source and authority

This page migrates DOCUMENTATION.md in full. It is an explanatory / implementation document, not the normative specification. Where it simplifies a rule, the Technical Specification governs. The original file is preserved in source-original/LANG/.