refactor: migrate Markdown to AsciiDoc (#725)

Automated migration of .md to .adoc per global rules, preserving wikis
and critical exceptions.

Author: hyperpolymath

.claude/PROJECT.adoc

@@ -0,0 +1,80 @@
+== AffineScript - Claude Code Instructions
+
+This is the AffineScript compiler, written in OCaml.
+
+=== Project Structure
+
+....
+affinescript/
+├── lib/           # Core compiler library
+│   ├── ast.ml     # Abstract syntax tree
+│   ├── token.ml   # Token definitions
+│   ├── lexer.ml   # Lexer (sedlex-based)
+│   ├── parser.ml  # Parser (menhir-based) [TODO]
+│   ├── span.ml    # Source location tracking
+│   └── error.ml   # Diagnostics and error handling
+├── bin/           # CLI executable
+│   └── main.ml    # Command-line interface
+├── test/          # Test suite
+└── docs/          # Documentation
+....
+
+=== Build Commands
+
+[source,bash]
+----
+# Build
+dune build
+
+# Run tests
+dune runtest
+
+# Format code
+dune fmt
+
+# Generate docs
+dune build @doc
+
+# Run compiler
+dune exec affinescript -- <command> <args>
+----
+
+=== Coding Conventions
+
+* Use descriptive variable names
+* All files should have type annotations where helpful
+* Error messages should follow the format in `+error.ml+`
+* Use `+ppx_deriving+` for show, eq, ord on types
+* Use `+sexp+` for serialization of AST types
+
+=== Language Specification
+
+The full language specification is at
+`+/var$HOME/affinescript-spec.md+`.
+
+Key language features: - *Partial by default*: Functions are partial
+unless marked `+total+` - *Quantity annotations*: `+0+` (erased), `+1+`
+(linear), `+ω+` (unrestricted) - *Row polymorphism*: `+{x: Int, ..r}+`
+for extensible records - *Extensible effects*: User-defined effects with
+`+effect+` keyword - *Ownership*: `+own+`, `+ref+`, `+mut+` modifiers
+
+=== Implementation Priority
+
+[arabic]
+. Lexer (sedlex) - in progress
+. Parser (menhir)
+. Name resolution
+. Type checker (bidirectional)
+. Borrow checker
+. Effect checking
+. WASM codegen
+
+=== Testing
+
+Tests go in `+test/+` directory. Use Alcotest:
+
+[source,ocaml]
+----
+let test_something () =
+  Alcotest.(check string) "description" expected actual
+----

.claude/PROJECT.md

@@ -0,0 +1,48 @@
+== Architecture
+
+=== Overview
+
+This repository follows a modular, maintainable architecture designed
+for clarity, scalability, and long-term sustainability.
+
+=== Directory Structure
+
+....
+.
+├── src/           # Source code
+├── tests/        # Test suites
+├── docs/         # Documentation
+├── scripts/      # Utility scripts
+├── config/       # Configuration files
+├── LICENSE       # License file
+├── LICENSES/     # Full license texts
+└── README.adoc   # Project documentation
+....
+
+=== Design Principles
+
+* *Separation of Concerns*: Each module has a single responsibility
+* *Testability*: Code is written to be easily testable
+* *Documentation*: All public APIs are documented
+* *Configuration*: Environment-specific settings are externalized
+
+=== Dependencies
+
+* External dependencies are minimized and clearly declared
+* Version pinning is used for reproducibility
+
+=== Security Considerations
+
+* Sensitive data is never committed to the repository
+* Secrets are managed through environment variables or secure vaults
+* Regular dependency audits are performed
+
+=== Maintainability
+
+* Code follows consistent style guidelines
+* Pull requests require review and CI checks
+* Issues and discussions are tracked transparently
+
+'''''
+
+_Last updated: 2026-07-18_