refactor: migrate Markdown to AsciiDoc

ARCHITECTURE.adoc

@@ -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_

CHANGELOG.adoc

@@ -0,0 +1,9 @@
+== Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on https://keepachangelog.com/en/1.1.0/[Keep a
+Changelog], and this project adheres to
+https://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+=== [Unreleased]

CODE_OF_CONDUCT.adoc

@@ -0,0 +1,24 @@
+== Contributor Covenant Code of Conduct
+
+=== Our Pledge
+
+We pledge to make participation a harassment-free experience for
+everyone.
+
+=== Our Standards
+
+*Positive behavior:* * Using welcoming language * Being respectful of
+differing viewpoints * Accepting constructive criticism * Focusing on
+what is best for the community
+
+*Unacceptable behavior:* * Harassment, trolling, or personal attacks *
+Publishing private information without permission
+
+=== Enforcement
+
+Report issues to the maintainers. All complaints will be reviewed.
+
+=== Attribution
+
+Adapted from https://www.contributor-covenant.org/[Contributor Covenant]
+v2.1.

CONTRIBUTING.adoc

@@ -0,0 +1,55 @@
+== Contributing to rattleScript
+
+This is a *brand-surface repo*. The compiler, type checker, borrow
+checker, codegen, and face transformer all live in
+https://github.com/hyperpolymath/affinescript[affinescript].
+
+=== Where to file what
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|Issue |Repo
+|The face transformer mangles my code
+|https://github.com/hyperpolymath/affinescript/issues[affinescript]
+
+|The error message uses the wrong vocabulary for this face
+|https://github.com/hyperpolymath/affinescript/issues[affinescript] —
+the face vocabulary lives in `+lib/face.ml+`
+
+|New language feature needed (extern types, dependent types, etc.)
+|https://github.com/hyperpolymath/affinescript/issues[affinescript]
+
+|Brand README is unclear / wrong |this repo
+
+|Example program doesn’t compile |this repo (and probably also
+affinescript if it’s a transformer bug)
+
+|Tutorial / migration guide additions |this repo
+
+|Add this face to my IDE / build tool |this repo, but expect it to
+depend on affinescript work first
+|===
+
+=== Local workflow
+
+[source,bash]
+----
+opam install affinescript     # installs the compiler
+git clone https://github.com/hyperpolymath/rattlescript
+cd rattlescript
+just hello                    # smoke-test the example
+just check examples/hello.affine
+just preview examples/hello.affine
+----
+
+=== Pull requests
+
+* SPDX header on every new file (`+AGPL-3.0-or-later+`).
+* Run `+just hello+` and any other examples added before opening the PR.
+* If you’re touching the face transformer, open the PR against
+https://github.com/hyperpolymath/affinescript[affinescript], not here.
+
+=== Code of conduct
+
+See `+CODE_OF_CONDUCT.md+` (TBD; for now follow the affinescript code of
+conduct).