feat: scaffold FPSMaxxing Rust workspace with typed contracts, CI, and OSS docs

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.rs]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,36 @@
+name: Bug report
+description: Report a reproducible problem that is not security-sensitive.
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not disclose privilege-boundary or unsafe hardware-control vulnerabilities here. Use private vulnerability reporting.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: input
+    id: revision
+    attributes:
+      label: Revision
+      placeholder: Commit SHA
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Minimal steps, logs, and relevant provider versions.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS build, CPU, GPU, motherboard, drivers, and installed providers.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/undeemed/fpsmaxxing/security/advisories/new
+    about: Report privilege, hardware-safety, or rollback vulnerabilities privately.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,37 @@
+name: Feature request
+description: Propose a capability, provider, evaluator, or safety improvement.
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What measurable user problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed approach
+      description: Describe the capability boundary rather than a raw command.
+    validations:
+      required: true
+  - type: dropdown
+    id: risk
+    attributes:
+      label: Expected risk class
+      options:
+        - Read-only
+        - Reversible
+        - Approval required
+        - Denied or unknown
+    validations:
+      required: true
+  - type: textarea
+    id: rollback
+    attributes:
+      label: Verification and rollback
+      description: How will the system prove the effect and restore the previous state?
+    validations:
+      required: true

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## Why
+
+<!-- What user or contributor problem does this solve? -->
+
+## What changed
+
+<!-- Keep the implementation summary concrete and scoped. -->
+
+## Safety and rollback
+
+- Risk class:
+- Privilege required:
+- Snapshot:
+- Verification:
+- Lease/rollback:
+- Conflicts:
+
+## Validation
+
+- [ ] `cargo fmt --all -- --check`
+- [ ] `cargo check --workspace --all-targets`
+- [ ] `cargo clippy --workspace --all-targets -- -D warnings`
+- [ ] `cargo test --workspace`
+- [ ] `cargo deny check`
+- [ ] Documentation updated

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  rust:
+    name: Rust (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Install pinned Rust toolchain
+        run: rustup toolchain install
+      - name: Cache Cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+      - name: Check workspace
+        run: cargo check --workspace --all-targets --locked
+      - name: Run Clippy
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings
+      - name: Run tests
+        run: cargo test --workspace --locked
+
+  cargo-deny:
+    name: Cargo deny
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Check advisories, bans, licenses, and sources
+        uses: EmbarkStudios/cargo-deny-action@bb137d7af7e4fb67e5f82a49c4fce4fad40782fe # v2.0.20
+
+  schemas:
+    name: JSON schemas
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Validate schemas against their declared metaschema
+        run: pipx run check-jsonschema --check-metaschema schemas/*.json

.gitignore

@@ -0,0 +1,21 @@
+/target/
+/dist/
+/.idea/
+/.vscode/
+*.user
+*.suo
+*.swp
+*.tmp
+*.log
+.DS_Store
+Thumbs.db
+
+# Local machine state must never enter source control.
+/.fpsmaxxing/
+/.env
+/.env.*
+!.env.example
+
+# .NET bridge output.
+**/bin/
+**/obj/

AGENTS.md

@@ -0,0 +1,35 @@
+# Agent instructions
+
+Start with `docs/README.md`. Read `docs/IMPLEMENTATION_PLAN.md`, `docs/ARCHITECTURE.md`, and `docs/threat-model/README.md` before changing architecture or privileged code.
+
+## Non-negotiable boundaries
+
+- The LLM-facing gateway is not privileged.
+- The broker never accepts raw shell commands, arbitrary Registry paths, arbitrary memory addresses, MSR indices, port I/O, or firmware variables.
+- Every mutating capability requires a pre-state snapshot, bounded parameters, a verification probe, a TTL lease, and rollback.
+- Unknown provider versions and unknown hardware fail closed.
+- Only one provider may own a knob at a time.
+- The watchdog must be able to restore state without the gateway or LLM.
+- BIOS, voltage, firmware flashing, Secure Boot, TPM, boot settings, and kernel patching are out of scope unless the implementation plan is explicitly amended.
+
+## Repository rules
+
+- Keep shared wire types in `crates/contracts`, and keep `schemas/*.json` in sync with them; the contract tests enforce matching fields and enum strings.
+- Keep provider lifecycle behavior in `crates/provider-sdk`.
+- Put provider-specific code in one `sidecars/<provider>` package; sidecars may not import each other.
+- Put non-Rust compatibility processes under `bridges/` and isolate them behind the sidecar protocol.
+- Do not vendor third-party binaries without confirmed redistribution rights.
+- Add tests before enabling a real write path.
+
+## Required validation
+
+```bash
+cargo fmt --all -- --check
+cargo check --workspace --all-targets
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+cargo deny check
+```
+
+`cargo deny check` requires [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) and enforces the advisory, ban, license, and source policies in `deny.toml`.
+CI runs the same checks, plus JSON schema validation, on every pull request and push to `main`.

CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Code of conduct
+
+## Our pledge
+
+We pledge to make participation in FPSMaxxing a harassment-free experience for everyone, regardless of background, identity, experience, or level of contribution.
+
+## Expected behavior
+
+- Be respectful, specific, and constructive.
+- Critique ideas and implementations, not people.
+- Prioritize safety, reproducibility, and evidence over hype.
+- Accept responsibility for mistakes and help repair their impact.
+
+## Unacceptable behavior
+
+Harassment, threats, discrimination, sexualized conduct, sustained disruption, publication of private information, or encouraging unsafe use of privileged hardware controls is not acceptable.
+
+## Enforcement
+
+Report conduct concerns privately to the maintainer through the contact methods on the maintainer's GitHub profile. Maintainers may remove content, restrict participation, or ban contributors when necessary to protect the community.

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+FPSMaxxing welcomes focused, reviewable contributions that preserve the project's safety boundaries.
+
+## Before opening a pull request
+
+1. Read `AGENTS.md` and `docs/IMPLEMENTATION_PLAN.md`.
+2. Open an issue before introducing a new privileged operation or changing a wire contract.
+3. Keep provider-specific code inside its provider package.
+4. Include negative-path and rollback tests for every state-changing operation.
+5. Run the full validation suite documented in `AGENTS.md`.
+
+## Pull request expectations
+
+- Explain the user problem and why the change belongs in FPSMaxxing.
+- List affected capabilities and risk classes.
+- Describe pre-state capture, verification, lease expiry, and rollback.
+- Document supported operating-system, provider, and hardware versions.
+- Include evidence for any performance claim.
+
+By submitting a contribution, you agree that it is licensed under Apache-2.0 as described in the repository license.