chore(repo): Add agents file alongside a few skills (#196)

## Summary

This branch adds repository-level Codex guidance and repo-local
authoring
skills. The final outcome is an `AGENTS.md` file for always-on
repository
policy, a Codex environment file, and two dedicated skills that handle
long-lived documentation and tutorial authoring workflows.

## Related Issues

None linked.

## Changes

- Added `AGENTS.md` with repository guidance for structure,
architecture,
coding practices, testing, pull requests, and documentation
requirements.
- Added `.codex/environments/environment.toml` to define the workspace
setup
  script for Codex.
- Added the `long-lived-docs-authoring` skill and its
`agents/openai.yaml`
  metadata for specs, plans, guides, and other durable Markdown docs.
- Added the `tutorial-authoring` skill and its `agents/openai.yaml`
metadata
  for step-by-step tutorials in `docs/tutorials/`.
- Kept the final `AGENTS.md` focused on repo-wide policy while pointing
  documentation-heavy workflows at the new skills.

## Type of Change

- [x] Feature (non-breaking change that adds functionality)
- [x] Documentation (updates to docs, specs, tutorials, or comments)
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Refactor (code change that neither fixes a bug nor adds a feature)
- [ ] Performance (change that improves performance)
- [ ] Test (adding or updating tests)
- [ ] Build/CI (changes to build process or CI configuration)

## Affected Crates

- [ ] `lambda-rs`
- [ ] `lambda-rs-platform`
- [ ] `lambda-rs-args`
- [ ] `lambda-rs-logging`
- [x] Other: repository tooling / Codex workspace metadata

## Checklist

- [ ] Code follows the repository style guidelines (`cargo +nightly fmt
--all`)
- [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D
warnings`)
- [ ] Tests pass (`cargo test --workspace`)
- [x] New code includes appropriate documentation
- [ ] Public API changes are documented
- [ ] Breaking changes are noted in this PR description

## Testing

**Manual verification steps (if applicable):**

N/A

## Screenshots/Recordings

Not applicable.

## Platform Testing

- [ ] macOS
- [ ] Windows
- [ ] Linux

## Additional Notes

- This branch changes repository guidance and Codex-specific tooling
only.
- No Rust crates or public APIs are modified.

Author: vmarcella

.codex/environments/environment.toml

@@ -0,0 +1,6 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "lambda-rs"
+
+[setup]
+script = "./scripts/setup.sh"

.codex/skills/long-lived-docs-authoring/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: long-lived-docs-authoring
+description: Use when drafting or revising long-lived repository documentation such as specs, roadmaps, guides, feature docs, or planning docs that need Lambda's required metadata, structure, and documentation style. Do not use for tutorials; use `tutorial-authoring` instead.
+---
+
+# Long Lived Docs Authoring
+
+Use this skill for durable Markdown documents that are meant to stay in the
+repository and be maintained over time. The goal is to apply Lambda's
+documentation metadata, tone, and maintenance rules without keeping those
+details in the main task prompt.
+
+## When To Use
+
+- New or updated specifications in `docs/specs/`.
+- Roadmaps, plans, feature documents, and other durable docs in `docs/`.
+- Documentation changes that need YAML front matter, changelog discipline,
+  and repository-specific style constraints.
+- Do not use this skill for tutorials in `docs/tutorials/`.
+- Do not use this skill for Rustdoc-only work.
+
+## Workflow
+
+1. Identify the document type and location.
+   Use `docs/specs/_spec-template.md` for new specifications instead of
+   starting from another spec.
+2. Add or preserve the metadata header.
+   Long-lived docs require YAML front matter with these fields:
+   `title`, `document_id`, `status`, `created`, `last_updated`, `version`,
+   `engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
+   `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
+3. Structure the document for maintenance.
+   Keep sections short, scannable, and diff-friendly. Specifications should
+   include a table of contents. Use stable headings and avoid unnecessary
+   renames.
+4. Apply repository documentation style.
+   Use clear, direct, neutral language in active voice. Prefer present tense.
+   Avoid conversational phrasing, rhetorical questions, marketing language,
+   speculation, emojis, exclamation-based emphasis, and AI authorship
+   references.
+5. Use consistent technical terminology.
+   Define acronyms on first use in each document. Prefer American English.
+   Refer to crates by name, such as `lambda-rs` and `lambda-rs-platform`.
+   Wrap code identifiers in backticks.
+6. Keep examples minimal and buildable.
+   Use concise Rust sketches when proposing APIs. Mirror the repository's
+   existing builder and command patterns. Use ASCII diagrams only and do not
+   embed binaries.
+7. Update maintenance metadata on substantive edits.
+   Update `last_updated`, bump `version` semantically, set `repo_commit` to
+   `HEAD`, and append or update the `Changelog` section.
+
+## Required Style Rules
+
+- Use RFC-2119 keywords when the content is normative.
+- Prefer `Rationale` bullets instead of long "Why" paragraphs.
+- Keep bullets short when possible.
+- Avoid filler sentences and meta commentary such as "this aims to".
+- Do not make unscoped promises such as "we will add" without a linked issue.
+
+## Validation Checklist
+
+- Metadata header is present and complete.
+- The file uses stable headings and short sections.
+- The tone is professional, direct, and repository-aligned.
+- Acronyms are defined on first use.
+- Code snippets are minimal and stylistically consistent with the repository.
+- `last_updated`, `version`, `repo_commit`, and `Changelog` are updated for
+  substantive edits.

.codex/skills/long-lived-docs-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Long-Lived Docs"
+  short_description: "Author specs, guides, and durable docs"
+  default_prompt: "Use $long-lived-docs-authoring to draft or revise a spec, roadmap, or guide for this repository."

.codex/skills/tutorial-authoring/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: tutorial-authoring
+description: Use when creating or revising step-by-step tutorials in `docs/tutorials/`. This skill applies Lambda's required metadata, instructional structure, tone, code-snippet rules, and validation expectations for tutorial documents.
+---
+
+# Tutorial Authoring
+
+Use this skill for tutorial documents that teach a discrete task in the
+repository. It includes the long-lived documentation rules that tutorials
+inherit, plus the additional section and narrative requirements specific to
+`docs/tutorials/`.
+
+## When To Use
+
+- New tutorials in `docs/tutorials/`.
+- Revisions to existing tutorials that change structure, examples, or prose.
+- Documentation tasks that teach a step-by-step workflow with validation and
+  exercises.
+- Do not use this skill for generic guides, specs, or roadmaps outside
+  `docs/tutorials/`.
+
+## Workflow
+
+1. Place the file correctly.
+   Tutorials belong in `docs/tutorials/` and should use kebab-case file names.
+   Include the `tutorial` tag in the metadata.
+2. Add the required metadata header.
+   Tutorials use the same YAML front matter fields as other long-lived docs:
+   `title`, `document_id`, `status`, `created`, `last_updated`, `version`,
+   `engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
+   `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
+3. Build the required section layout.
+   Tutorials should include a table of contents and these sections:
+   `Goals`, `Overview`, `Prerequisites`, `Implementation Steps`,
+   `Validation`, `Notes`, `Conclusion`, `Exercises`, and `Changelog`.
+4. Write each implementation step as instruction plus outcome.
+   Explain intent and rationale before each code block. After each code block,
+   include a short paragraph describing the resulting state and why it matters.
+5. Keep the instructional tone precise.
+   Use a book-like instructional narrative while staying professional and
+   direct. Imperative phrasing is preferred. Limited second-person phrasing is
+   acceptable when it clearly improves the instruction.
+6. Keep terminology and examples consistent.
+   Define acronyms on first use, use terms such as `GPU`, `CPU`, `wgpu`,
+   `bind group`, and `pipeline layout` consistently, and refer to identifiers
+   with backticks.
+7. Keep code snippets minimal and repository-aligned.
+   Match repository style: 2-space indentation, line width near 80 columns,
+   explicit return statements, and no abbreviations or acronyms in code
+   identifiers. Prefer workspace-relative file paths in prose and examples.
+8. Update maintenance metadata on substantive edits.
+   Update `last_updated`, bump `version` semantically, set `repo_commit` to
+   `HEAD`, and maintain the `Changelog`.
+
+## Required Style Rules
+
+- Use clear, direct, neutral language.
+- Prefer active voice and present tense.
+- Avoid conversational filler, rhetorical questions, emojis, marketing claims,
+  speculation, and AI authorship references.
+- Use RFC-2119 keywords in `Notes` when the content is normative.
+- Do not include commentary about internal process documents or guideline
+  updates.
+
+## Validation Checklist
+
+- The tutorial lives under `docs/tutorials/` with a kebab-case file name.
+- Metadata header and `tutorial` tag are present.
+- A table of contents is present.
+- All required sections are present and ordered clearly.
+- Each implementation step includes intent before the code and outcome after it.
+- Code snippets are minimal, buildable, and repository-aligned.
+- `Validation` contains exact commands and expected behavior.
+- `Exercises` contains 5 to 7 focused follow-up tasks.

.codex/skills/tutorial-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Tutorial Authoring"
+  short_description: "Write repository tutorials with the required structure"
+  default_prompt: "Use $tutorial-authoring to create or revise a tutorial for this repository."

AGENTS.md

@@ -0,0 +1,186 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Lambda is organized as a Cargo workspace with multiple crates.
+
+- Core engine code lives in `crates/lambda-rs`.
+- Platform and dependency abstractions live in
+  `crates/lambda-rs-platform`.
+- CLI parsing utilities live in `crates/lambda-rs-args`.
+- Logging utilities live in `crates/lambda-rs-logging`.
+
+Shared tooling lives under `lambda-sh/` and `scripts/`.
+
+- Shader and logo assets are versioned in `crates/lambda-rs/assets/`.
+- Integration tests live in `crates/lambda-rs/tests/`.
+
+Run `scripts/setup.sh` once to install git hooks and `git-lfs`.
+Use `cargo build --workspace` for a full Rust build and
+`cargo test --workspace` to exercise unit and integration suites.
+Example binaries can be launched with `cargo run --example minimal`
+while iterating.
+
+## Project Architecture & Structure
+
+### General Architecture Rules
+
+- `lambda-rs` is the primary API exposed to end users and MUST NOT leak
+  internal platform or dependency details.
+- `lambda-rs-platform` contains lower-level abstractions and dependency
+  wrappers and SHOULD be designed to support the needs of the higher-level
+  framework.
+- Use the builder pattern where appropriate to expose resources provided by
+  the APIs, such as windows, GPUs, shaders, and audio streams.
+- In libraries exposed by this repository, avoid panics unless absolutely
+  necessary and allow the caller to handle errors whenever possible.
+- Errors SHOULD be actionable and descriptive, including context about the
+  cause of the failure.
+
+### `lambda-rs`
+
+`lambda-rs`, located in `crates/lambda-rs`, is the primary API offered by
+this repository. It is a high-level framework for building desktop
+applications, games, and other GPU-backed software.
+
+- Do not expose dependency code to end users unless absolutely necessary.
+  Lower-level dependency or vendor code SHOULD be abstracted in
+  `lambda-rs-platform` and consumed from there.
+
+### `lambda-rs-platform`
+
+`lambda-rs-platform`, located in `crates/lambda-rs-platform`, is the
+platform and dependency abstraction layer. This library provides wrappers
+around dependency code used by `lambda-rs`, allowing the primary API to stay
+focused on higher-level abstractions.
+
+- APIs in this crate SHOULD aim for stable interfaces for `lambda-rs`, but
+  this crate is still treated as an internal support layer.
+  Non-backward-compatible changes are acceptable when they are required to
+  support the primary framework.
+
+## Coding Practices, Style, & Naming Conventions
+
+- Follow Rust 2021 idioms with 2-space indentation and `max_width = 80`,
+  as enforced by `rustfmt.toml`.
+- Always run `cargo +nightly fmt --all` and
+  `cargo clippy --workspace --all-targets -- -D warnings` before sending
+  changes.
+- Module and file names MUST remain `snake_case`.
+- Public types MUST use `UpperCamelCase`.
+- Constants MUST use `SCREAMING_SNAKE_CASE`.
+- Use explicit return statements.
+- Do not use abbreviations or acronyms for variable names.
+- Maintain readable spacing in new statements: keep spaces after keywords,
+  around operators, and after commas and semicolons instead of tightly packed
+  tokens.
+- Add comprehensive documentation to all code and tests.
+- Add documentation to code that is complex or not immediately clear.
+
+### Rustdoc Requirements
+
+- All public functions, methods, and types MUST have Rustdoc comments.
+- Non-trivial private helper functions SHOULD have Rustdoc comments.
+- Rustdoc for new or changed APIs MUST follow this structure:
+  - One-line summary sentence describing behavior.
+  - Optional paragraph describing nuances, constraints, or invariants.
+  - `# Arguments` section documenting each parameter.
+  - `# Returns` section describing the return value.
+  - `# Errors` section for `Result`-returning APIs describing failure cases.
+  - `# Panics` section only if the implementation can panic. Prefer avoiding
+    panics in library code.
+  - `# Safety` section for `unsafe` APIs describing required invariants.
+
+- Do not add comments explaining why code was removed where that code used to
+  be.
+
+### Feature Flags & Documentation
+
+- Non-essential code with production runtime cost, such as validation or
+  extra logging, MUST be disabled by default in release builds and guarded
+  behind explicit Cargo features. Debug builds MAY enable such checks via
+  `debug_assertions`.
+- Add features in the crate that owns the behavior. For example, rendering
+  validation features belong in `lambda-rs`.
+- Prefer narrowly scoped feature flags over broad umbrella flags. Umbrella
+  bundles MAY exist for convenience but MUST NOT be enabled by default.
+- Umbrella Cargo features, such as `render-validation`,
+  `render-validation-strict`, and `render-validation-all`, MUST only compose
+  granular feature flags.
+- Code and documentation MUST gate behavior using granular feature names, such
+  as `render-validation-encoder` and `render-validation-instancing`, together
+  with `debug_assertions`, never umbrella names.
+- Every granular feature that toggles behavior MUST be included in at least
+  one umbrella feature for discoverability and consistency.
+- Public `lambda-rs` features MUST NOT leak platform or vendor details. Map
+  high-level features to `lambda-rs-platform` internals as needed.
+- Specifications that add or change behavior MUST list the exact Cargo
+  features they introduce or rely on. The same change MUST also update
+  `docs/features.md` with the feature name, owning crate, default state
+  (debug or release), summary, and expected runtime cost.
+- Do not include performance-impacting features in a crate's `default`
+  feature set.
+
+## Testing Guidelines
+
+Unit tests live alongside the code. Integration test coverage lives under
+`crates/lambda-rs/tests/`, with runnable scenarios defined in
+`crates/lambda-rs/tests/runnables.rs`.
+
+- Add focused tests for new render paths or platform shims, grouped by
+  feature.
+- Run `cargo test -p lambda-rs -- --nocapture` when debugging rendering
+  output.
+- Maintain coverage by updating or extending runnable scenarios and examples.
+- Document non-trivial manual verification steps in the pull request body.
+
+## Commit & Pull Request Guidelines
+
+Commit messages follow the `[scope] message` style used in `git log`, such as
+`[add] logging crate to packages.` Each commit SHOULD remain narrowly scoped
+and buildable.
+
+Pull requests MUST:
+
+- Describe the intent of the change.
+- List the test commands that were run.
+- Link any tracking issues.
+- Include screenshots or clips for visual changes.
+- Note any required platform checks so reviewers can reproduce the change.
+
+## Setup & Tooling Tips
+
+- Run `scripts/setup.sh`, then enable the bundled hooks with
+  `pre-commit install`.
+- When working with the C++ engine archive, respect the `lambda_args_*`
+  options exposed by `lambda-sh/lambda.sh` for consistent builds.
+- Store large assets through `git-lfs` to keep history lean.
+
+## Documentation Skills
+
+Use the repo-local Codex skills for detailed documentation workflows.
+
+- Use `.codex/skills/long-lived-docs-authoring/SKILL.md` for specs, roadmaps,
+  guides, plans, and other long-lived Markdown documents.
+- Use `.codex/skills/tutorial-authoring/SKILL.md` for step-by-step tutorials
+  in `docs/tutorials/`.
+- Keep repo-wide policy in this file and keep detailed documentation authoring
+  workflow in those skills.
+
+## Documentation Requirements
+
+- Long-lived docs MUST include YAML front matter with `title`,
+  `document_id`, `status`, `created`, `last_updated`, `version`,
+  `engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
+  `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
+- New specifications MUST be created from `docs/specs/_spec-template.md`.
+- Specifications and tutorials MUST include a table of contents.
+- Substantive documentation edits MUST update `last_updated`, `version`,
+  `repo_commit`, and the `Changelog`.
+- Long-lived docs MUST use a professional, precise tone with active voice,
+  consistent terminology, American English spelling, and RFC-2119 keywords
+  where appropriate.
+- Tutorials MUST live in `docs/tutorials/`, use kebab-case filenames, include
+  the `tutorial` tag, and include `Goals`, `Overview`, `Prerequisites`,
+  `Implementation Steps`, `Validation`, `Notes`, `Conclusion`, `Exercises`,
+  and `Changelog`.