zard 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0551d23261849efc4c7967195baade2229626abf6b5dcdd653681787c968e19d
+  data.tar.gz: e08b3a10d55ec03987f22b505116f1e839d49769522d76f12c66efb9b7929990
+SHA512:
+  metadata.gz: e6631158d5562709a1846e7088384139894e1774f8c74478de4fa776336922af76098532282bcccb6cbb3821640a63f27a2c70c8835faa3dc381f4d4a6ec00c4
+  data.tar.gz: efe0e597d3d2e4fbb255aaf0edeb01ea0242b4d2022d11816be0e045526cf78b8b36c11990bf2d68d1a4a05338a61b241d747872a9a98a536e7837ba6b2a387c

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-11
+
+The first ZARD release separates Ruby API documentation from RBS and Rigor contracts. Parse Ruby source into a versioned model, generate public API Markdown, and lint documentation from files, directories, or standard input without installing Rigor.
+
+### Added
+
+- Parse Ruby source into `Zard::Model::V1` declarations with documentation, contracts, diagnostics, and source provenance.
+- Preserve plain RBS and `@extrbs` contract payloads and InlineRBS contract notes separately from API documentation.
+- Support class, module, constant, attribute, and method documentation, including aliases, module functions, literal method-definition calls, and Ruby refinements.
+- Model literal container builders such as `Data.define`, `Struct.new`, `Class.new`, `Module.new`, and `DelegateClass`, with generated attributes and block members.
+- Preserve explicit superclass, mixin, singleton receiver, and refinement target expressions without resolving runtime ancestry or object identity.
+- Apply supported visibility, removal, reassignment, and redefinition operations within the modeled source scope.
+- Render documented public declarations as Markdown with parameter, return, block, option, exception, note, reference, deprecation, and example tags, including multiline descriptions.
+- Lint noncanonical or YARD-like documentation syntax, empty descriptions, UTF-8 requirements, and Ruby syntax errors, with an option to fail on warnings.
+- Provide `zard-doc render` and `zard-doc lint` for files, recursive directories, and standard input, with deterministic path ordering and no partial Markdown on input errors.
+- Distribute `zard` and `zard-doc` as separate gems for Ruby 3.2 and newer, with a usage guide and a complete multi-file example.
+
+[Unreleased]: https://github.com/rigortype/zard/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/rigortype/zard/tree/v0.0.1

data/CONTEXT.md

@@ -0,0 +1,93 @@
+# ZARD
+
+ZARD is a Ruby self-documentation notation for people and AI agents. It uses plain RBS contracts, Rigor extensions, and separate API documentation so that prose does not require repeated type text.
+
+## Language
+
+**ZARD**:
+The self-documentation language defined by this project.
+_Avoid_: YARD, RDoc
+
+**InlineRBS**:
+RBS type notation written in Ruby source comments.
+_Avoid_: YARD type syntax
+
+**RBS::Extended**:
+Rigor's extra type information attached to RBS declarations.
+_Avoid_: a second type system
+
+**Contract**:
+A type-facing statement about Ruby code. Plain RBS contracts use `@rbs` or `#:`; extended contracts use `@extrbs`.
+_Avoid_: API description
+
+**`@extrbs`**:
+A typed comment channel for contract information that plain RBS cannot express. It may carry plain RBS, but `@rbs` and `#:` are preferred for plain RBS.
+_Avoid_: API documentation tag
+
+**API documentation**:
+Human-facing information about a public Ruby declaration.
+_Avoid_: type contract
+
+**Declaration**:
+A Ruby class, module, constant, attribute, or method represented in the versioned ZARD model.
+_Avoid_: documentation item
+
+**Alias target**:
+The method name that an alias refers to in the same Ruby scope.
+_Avoid_: copied documentation
+
+**Superclass reference**:
+The source expression explicitly named after `<` in a Ruby class declaration.
+_Avoid_: resolved ancestry, inferred parent
+
+**Container builder reference**:
+A source call assigned to a constant to create a class or module, such as `Data.define`, `Struct.new`, `Class.new`, or `Module.new`.
+_Avoid_: superclass reference, resolved container
+
+**Mixin reference**:
+An `include`, `prepend`, or `extend` target written in a Ruby class or module body.
+_Avoid_: resolved ancestor
+
+**Receiver reference**:
+The source expression that owns an explicitly received singleton declaration or a `class <<` body.
+_Avoid_: resolved object, inferred owner
+
+**Refinement target**:
+The source expression named by `refine` that scopes its declarations separately from the enclosing module.
+_Avoid_: enclosing module member, resolved class
+
+**Documentation claim**:
+An optional type written in an API documentation tag. Rigor may check it, but it does not replace a contract or an inferred fact.
+_Avoid_: authoritative type
+
+**Contract note**:
+Prose attached to a typed contract for people reading the code directly.
+_Avoid_: API documentation
+
+**Rigor fact**:
+Type or provenance information produced by Rigor from code, contracts, and analysis.
+_Avoid_: documentation claim
+
+**Rigor lens**:
+A structured summary of code, contracts, Rigor facts, and diagnostics.
+_Avoid_: a second analyzer
+
+**Grammar revision**:
+A named revision of the `@extrbs` type grammar that a tool reads or writes.
+_Avoid_: package version
+
+**Provenance**:
+The source, location, syntax, and origin of a contract, documentation item, or fact.
+_Avoid_: inferred origin
+
+**ZARD documentation marker**:
+The em dash `—` that separates a named documentation tag or an optional type from its description. A tag with neither a name nor a type writes its description directly, without this marker.
+_Avoid_: `--` in documentation tags
+
+**Documentation continuation line**:
+A plain comment line that extends the preceding canonical ZARD documentation tag until another annotation or contract begins.
+_Avoid_: explicit continuation marker
+
+**YARD-like comment**:
+A familiar documentation tag without the ZARD em dash. It may be preserved as raw text, but it is not a ZARD documentation claim.
+_Avoid_: ZARD documentation

data/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

data/README.md

@@ -0,0 +1,170 @@
+# ZARD
+
+**ZARD** is an AI-friendly Ruby self-documentation notation built around RBS and Rigor extensions. It keeps human-facing API documentation separate from type contracts.
+
+> **Status**: Under active design (pre-1.0). The current release slice parses Ruby source into a versioned model (`Zard::Model::V1`) and renders public API documentation as Markdown.
+
+---
+
+## Why ZARD?
+
+In traditional Ruby documentation tools (such as YARD or RDoc), type annotations and descriptive prose are often mixed within comment tags (e.g. `@param [String] path The path`). This creates redundant, easily desynchronized type definitions alongside modern Ruby type checkers.
+
+ZARD separates contracts from API documentation:
+
+- **Type Contracts (`@rbs`, `#:`, `@extrbs`)**: Plain RBS expresses contracts for the Ruby type ecosystem. Rigor-specific refinements use `@extrbs`.
+- **API Documentation (`@param`, `@return`, etc.)**: Human- and AI-facing prose explains *what* and *why* without repeating type signatures.
+- **Structured Declaration Model**: The parser captures declarations, contracts, documentation, and diagnostics with precise source spans and provenance—ideal for IDEs, automated tooling, and AI agents.
+
+The current release preserves contract payloads as text. It does not parse or validate their types, check documentation claims against contracts, or integrate with the Rigor lens.
+
+---
+
+## Syntax at a Glance
+
+ZARD separates type contracts from API prose:
+
+```ruby
+# @extrbs return: non-empty-string
+# @rbs path: String
+# @rbs return: String
+# @param path — Path to the name file.
+# @return The stored name.
+# @raise IOError — If the file cannot be read.
+def read_name(path)
+  File.read(path).strip
+end
+```
+
+- **Contracts**: Plain RBS uses `@rbs` or `#:`. Advanced Rigor-only refinements use `@extrbs`. Contract payloads are not copied into API documentation. Inline RBS trailing prose after `--` is stored as a contract note, not API prose.
+- **Documentation Marker**: An em dash (`—`) separates named documentation tags (`@param`, `@yieldparam`, `@raise`, `@option`) or optional type claims from descriptions.
+- **Tags without names or type claims**: Tags such as `@return`, `@note`, and `@example` write their descriptions directly without an em dash.
+- **Continuations**: Plain comment lines continue documentation text until the next annotation or contract.
+- **Encoding**: ZARD documentation requires UTF-8 source text.
+
+---
+
+## Architecture & Packages
+
+This repository provides two coordinated gems:
+
+| Gem | Role | Description |
+| --- | --- | --- |
+| [`zard`](.) | Parser & Model | Parses Ruby source into a versioned, static document model (`Zard::Model::V1`) with source spans and provenance. |
+| [`zard-doc`](zard-doc) | Renderer & CLI | Renders API documentation from the ZARD model into Markdown, and provides the `zard-doc` CLI tool. |
+
+---
+
+## Installation
+
+The `0.0.1` release candidate is not yet published on RubyGems. Use the repository as the Gem source:
+
+```ruby
+# Gemfile
+gem "zard", github: "rigortype/zard"
+gem "zard-doc", github: "rigortype/zard"
+```
+
+Once published, install with:
+
+```ruby
+# Gemfile
+gem "zard", "~> 0.0.1"
+gem "zard-doc", "~> 0.0.1"
+```
+
+Run `bundle install` after adding the gems to your Gemfile.
+
+**Requirements**: Ruby `>= 3.2.0`. The project is pre-1.0; compatibility guarantees for future releases have not yet been established.
+
+---
+
+## Quick Start & Usage
+
+For in-depth guides, model inspection, and exit codes, see the [Usage Guide](docs/usage.md).
+
+### Command Line (`zard-doc`)
+
+Lint Ruby source files or directories:
+
+```sh
+# Lint files or directories (warnings do not fail by default)
+bundle exec zard-doc lint lib
+
+# Fail in CI if any warnings or errors are reported
+bundle exec zard-doc lint --fail-on warning lib
+```
+
+Render Markdown documentation to standard output:
+
+```sh
+# Render API documentation to stdout
+bundle exec zard-doc render lib
+
+# Read Ruby source from stdin using '-'
+printf '%s\n' '# @return The value.' 'def value = 1' | bundle exec zard-doc render -
+```
+
+**Exit Codes**:
+
+- `0`: Success (no diagnostic met the failure threshold).
+- `1`: Diagnostic error (or warning when `--fail-on warning` is set), or render error.
+- `2`: Invalid CLI usage, no Ruby sources found, or unreadable input.
+
+### Ruby API
+
+```ruby
+require "zard"
+require "zard/doc"
+
+# 1. Parse Ruby source into the versioned model
+source = File.read("lib/example.rb")
+document = Zard.parse(source, path: "lib/example.rb")
+
+# 2. Render public API documentation as Markdown
+markdown = Zard::Doc.render(document)
+```
+
+The renderer emits documented public declarations and supports class, module, constant, attribute, and method prose, as well as `@param`, `@return`, `@yieldparam`, `@yieldreturn`, `@option`, `@raise`, `@note`, `@see`, `@deprecated`, and `@example`. Contracts remain in the model and are not duplicated into API prose.
+
+---
+
+## Supported Ruby Semantics
+
+The parser models supported Ruby declarations statically without executing code. Runtime ancestry, dynamic names, and foreign object evaluations remain unresolved.
+
+- Public declarations are rendered; private and protected declarations remain available in the model.
+- Supported forms include visibility modifiers, attributes, aliases, method removal, and literal method definitions.
+- Class and module builders, mixins, singleton declarations, and refinements retain source references and provenance.
+- Constant visibility, removal, replacement, and conditional initialization are modeled.
+
+See the [supported Ruby syntax guide](docs/supported-ruby-syntax.md) for exact forms and limits.
+
+---
+
+## Development
+
+Set up dependencies and run the test suite:
+
+```sh
+bin/setup
+bundle exec rake
+```
+
+The default rake task runs tests, StandardRB linting, RBS type validation, and gem packaging.
+
+---
+
+## Documentation & References
+
+- [Usage Guide](docs/usage.md) — CLI options, model inspection, and exit codes.
+- [Supported Ruby Syntax](docs/supported-ruby-syntax.md) — Declaration forms and static analysis limits.
+- [Design Context (`CONTEXT.md`)](CONTEXT.md) — Core vocabulary, design principles, and anti-patterns.
+- [Architecture Decision Records (`docs/adr/`)](docs/adr) — ADRs documenting syntactic and architectural decisions.
+- [Catalog Example](examples/catalog) — Complete multi-file example with [expected Markdown](examples/catalog/expected.md).
+
+---
+
+## License
+
+ZARD is open-source software available under the [Mozilla Public License 2.0](LICENSE).

data/docs/adr/0001-contract-and-documentation-channels.md

@@ -0,0 +1,13 @@
+# Separate contract channels from API documentation
+
+ZARD reads typed contracts from `@rbs`, `#:`, and `@extrbs`, and keeps API documentation in tags such as `@param` and `@return`. Plain RBS belongs in `@rbs` or `#:`, while `@extrbs` carries information that plain RBS cannot express; plain RBS in `@extrbs` is valid but not preferred. This lets people and AI agents write useful prose without making type text mandatory, while Rigor can check optional documentation claims without treating them as the source of truth.
+
+## Consequences
+
+- `@rbs` and `#:` remain the public contract forms that other RBS tools can read inline.
+- `@extrbs` uses the `@rbs` tag forms and carries Rigor's extended type vocabulary.
+- API documentation may omit types.
+- A type in an API documentation tag is an optional documentation claim.
+- When a documentation claim conflicts with a contract, the contract wins and Rigor reports the conflict.
+- `zard-doc lint` may warn when a documentation claim only repeats the contract.
+- Contract notes and API documentation remain separate.