// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2024-2026 hyperpolymath (Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>)

= AffineScript Documentation Directory

This directory contains all project documentation organized by purpose.

== Structure

[source]
----
docs/
├── README.adoc               # This file
├── specs/                    # Language specifications
│   ├── affinescript-spec.md  # Complete language specification
│   └── SPEC.adoc             # Core specification
├── governance/               # Community and process docs
│   ├── CODE_OF_CONDUCT.md    # Community standards
│   ├── CONTRIBUTING.adoc     # How to contribute
│   ├── MAINTAINERS.adoc      # Project maintainers
│   └── SECURITY.md           # Security policy
├── standards/                # Design & planning docs
│   ├── ROADMAP.md            # Development roadmap
│   ├── DECISIONS.md          # Architecture decisions
│   ├── RELEASE.md            # Release procedures
│   ├── TESTING.adoc          # Test taxonomy + PR-level gates
│   ├── PANIC-ATTACK.adoc     # Security-scan policy & disposition
│   └── PALIMPSEST.adoc       # License integration
└── guides/                   # Testing and guides
    ├── TESTING-REPORT.adoc   # (RETIRED — redirects to standards/TESTING.adoc)
    └── TESTING-REPORT.scm    # (RETIRED — redirects to standards/TESTING.adoc)
----

== Documentation Categories

=== Language Specifications (`specs/`)

**For language designers and implementers.**

* link:specs/affinescript-spec.md[AffineScript Specification] - Complete language spec
* link:specs/SPEC.adoc[Core Specification] - Core language features
* link:specs/TYPED-WASM-INTERFACE.adoc[Typed-WASM Interface (v1)] - Formal AS↔typed-wasm contract (carrier, levels, CLI, tests, multi-producer model)
* link:specs/TYPED-WASM-ROADMAP.adoc[Typed-WASM Widening Roadmap] - Tranches A–E for making typed-wasm a natural + optimal target
* link:specs/SETTLED-DECISIONS.adoc[Settled Decisions] - ADR index

=== Governance (`governance/`)

**For contributors and community members.**

* link:governance/CODE_OF_CONDUCT.md[Code of Conduct] - Community behavior standards
* link:governance/CONTRIBUTING.adoc[Contributing Guide] - How to contribute code/docs
* link:governance/MAINTAINERS.adoc[Maintainers] - Who maintains what
* link:governance/SECURITY.md[Security Policy] - How to report vulnerabilities

=== Standards & Planning (`standards/`)

**For understanding project direction and decisions.**

* link:standards/ROADMAP.adoc[Roadmap] - Development roadmap and milestones
* link:standards/DECISIONS.adoc[Architecture Decisions] - Key design choices
* link:standards/RELEASE.adoc[Release Process] - How releases are made
* link:standards/PALIMPSEST.adoc[Palimpsest Integration] - License integration
* link:standards/TESTING.adoc[Testing Standards] - Test taxonomy, gate baseline, PR expectations
* link:standards/PANIC-ATTACK.adoc[Panic-Attack Policy] - Security-scan SOP and finding disposition

=== Guides (`guides/`)

**For testing and quality assurance.**

* link:CAPABILITY-MATRIX.adoc[Capability Matrix] - **Live** per-component readiness (the authoritative status doc)
* link:standards/TESTING.adoc[Testing Standards] - Test taxonomy, gate baseline, PR expectations
* link:guides/TESTING-REPORT.adoc[Testing Report] - *RETIRED* (2025-12-29 snapshot; redirects to the two above)

== Quick Links by Role

=== I want to...

**...understand AffineScript**
→ Start with link:specs/affinescript-spec.md[Language Specification]

**...contribute code**
→ Read link:governance/CONTRIBUTING.adoc[Contributing Guide]

**...report a security issue**
→ Follow link:governance/SECURITY.md[Security Policy]

**...understand design decisions**
→ See link:standards/DECISIONS.adoc[Architecture Decisions]

**...check the roadmap**
→ Review link:standards/ROADMAP.adoc[Roadmap]

**...see test coverage**
→ Browse link:CAPABILITY-MATRIX.adoc[Capability Matrix] (live) or link:standards/TESTING.adoc[Testing Standards] (taxonomy + gates)

== Contributing to Documentation

Documentation improvements are always welcome! See link:governance/CONTRIBUTING.adoc[Contributing Guide] for:

* Style guidelines
* Review process
* Documentation testing

## External Resources

* **Project Repository**: https://github.com/hyperpolymath/affinescript
* **Issue Tracker**: https://github.com/hyperpolymath/affinescript/issues
* **Discussions**: https://github.com/hyperpolymath/affinescript/discussions

---

**Last updated:** 2026-01-23
