add docs

INSTRUCTIONS.md

@@ -0,0 +1,20 @@
+Your job is to create documentation to aid new members of an FTC team in learning all the software + some electronics they need to know to succeed in FTC. The documentation should assume nothing except java knowledge. It should be organized in a way that is easy to follow and understand, with clear explanations and examples.
+
+First let's go over the structure of the documentation:
+There are 2 folders that will eventually be removed and you should not concern yourself with them. They are the `java` and `markdown` folders.
+This file is `INSTRUCTIONS.md`
+There is a `PLANNING.md` file that has a very rough outline of what I want the documentation to look like.
+The `README.md` file is going to be the main entry point for the documentation. It's audience is new members of the team, and it should explain how to use the documentation, and where to start. It is not up to date. You will need to update it.
+There are 2 more folders: `codebase` and `intro`. These contain current documentation that has been written already. You should use this documentation as a reference for the style and format of the documentation you will be writing. The `codebase` folder contains documentation about the codebase, and the `intro` folder contains documentation about the basics of FTC and robotics in general. These folders are not necessarily complete.
+
+Your job will be completed in 2 steps:
+The first is to make a more detailed outline of the documentation. I need you to expand on the contents of `PLANNING.md` and make a more detailed outline in `OUTLINE.md`. This is for you to use later, and I may edit parts of it if I see fit. It should organize everything into a logical structure that shows where each file goes, and what will be the different parts of each file. Please also include the already completed reference documentation in the outline as well. If you need to change any of the organization in `PLANNING.md` that's perfectly fine.
+
+The second step will be to actually write the documentation. You will use the outline you created in the first step to guide you in writing the documentation. You should write the documentation in a clear and concise manner, with examples and explanations that are easy to understand. You should also make sure to include any relevant information that you think would be helpful for new members of the team.
+
+Some more things to note:
+The code style is to be consistent with previous years that our team has competed. Our team is Stuy Fission 310. I have put an old codebase from the power play season in the `power-play` folder. You should use this codebase as a reference for the code style and structure that we have used in the past. It will not be in the final documentation. We also have our own library of utils that we use called `FissionLib`. This is in the `FissionLib` folder. Please use this as a reference as well.
+In case you need any information regarding FTC programming I have also included `gm0.org` documentation in the `gm0` folder. Feel free to use this as a reference too. gm0 is extremely useful for learning about FTC, and thus should be linked in this documentation as well. I will obviously not include the whole `gm0` documentation, but it's here for your reference. If there is any additional information that you are not sure about, please make a note either in the outline, or in the documentation, and tell me about it so I can provide you with the correct information.
+One final thing is that previously we have used RoadRunner for our drivetrain. Some of the existing documentation references RoadRunner, and the `power-play` repo also does. However, we are switching to PedroPathing. Make sure the documentation you write is updated for pedro pathing and not roadrunner. Please also write patches for the existing documentation as well. I have included the pedro pathing documentation in the `pedro` folder.
+
+Please start step 1. Stop when you are done, I will review the outline and then we can move on to step 2.

OUTLINE.md

@@ -0,0 +1,294 @@
+# Newbie Education Documentation Outline (Step 1)
+
+This outline expands `PLANNING.md` into a concrete, file-by-file documentation plan for new FTC software/electronics members.
+
+## Goals and Audience
+- Audience: brand-new FTC members with basic Java knowledge.
+- Goal: teach practical setup, codebase navigation, mechanism development, TeleOp, autonomous (PedroPathing), debugging, and team workflow.
+- Style target: match current docs in `intro/` and `codebase/` (plain language, concrete examples, progressive complexity).
+
+## Existing Material Included as Reference
+
+### Already Written (Keep + integrate)
+- `intro/00-setup.md`
+- `intro/01-code-overview.md`
+- `codebase/mechanisms/00-intro.md`
+- `codebase/mechanisms/01-robot-scoring.md`
+
+### Existing Material Requiring Patches in Step 2
+- `intro/01-code-overview.md`
+  - Replace RoadRunner-focused section with PedroPathing-focused structure and terminology.
+  - Keep conceptual role of motion-planning libraries, but update folder/file examples to current PedroPathing usage.
+
+### Reference Sources (not part of final lesson set)
+- `power-play/` (team historical style, opmode organization, dev opmodes, hardware/mechanism patterns)
+- `FissionLib/` (team utility conventions + dependency setup)
+- `gm0/` (external FTC learning reference to link where useful)
+- `pedro/` (PedroPathing docs and setup flow)
+
+---
+
+## Proposed Final Documentation Structure
+
+### 0) Main entry and usage guide
+
+#### `README.md` (rewrite in Step 2)
+Purpose: onboarding index + learning path.
+
+Sections:
+1. What this documentation is and who should use it
+2. How to use this curriculum (self-study + with mentor + during season)
+3. Recommended order (Intro → Codebase → TeleOp → Auton → Advanced)
+4. Time estimates per section
+5. Prerequisites and required tools
+6. External references
+   - FTC SDK docs
+   - gm0
+   - PedroPathing docs
+7. Contributing/fixing docs
+
+---
+
+### 1) Intro track (`intro/`)
+
+#### Existing: `intro/00-setup.md` (patch)
+Keep most content; improve for clarity and current workflow.
+
+Planned section layout:
+1. Why Android Studio + Git in FTC
+2. Install checklist (Android Studio, Git, GitHub auth)
+3. Clone FTC base + team code flow
+4. Import project and first successful build
+5. Common setup failures
+   - Gradle sync failures
+   - SDK/platform mismatch
+   - Git auth issues
+6. Verification checklist before moving on
+
+#### Existing: `intro/01-code-overview.md` (major patch)
+Planned section layout:
+1. TeamCode vs teamcode clarity
+2. Core folders (`hardware`, `opmode`, etc.)
+3. How hardware classes and opmodes interact
+4. Autonomous stack overview (PedroPathing, not RoadRunner)
+5. Where to find tuning/test opmodes
+6. Reading assignment: one TeleOp + one Auton walkthrough
+
+#### New: `intro/02-git-workflow.md`
+1. Why Git matters during build season
+2. Branch naming and PR expectations (team conventions)
+3. Typical daily workflow
+   - pull/rebase
+   - branch
+   - commit small
+   - push
+   - PR
+4. Resolving conflicts safely
+5. Git mistakes to avoid
+6. Mini exercise: add/change a mechanism constant and open PR
+
+#### New: `intro/03-android-studio-workflow.md`
+1. Project/tool windows and navigation tips
+2. Running opmodes and logcat basics
+3. Build variants and sync/build cycle
+4. Device connection basics (Control Hub / ADB overview)
+5. Common compile errors and fast triage
+6. Recovery checklist when “everything is broken”
+
+---
+
+### 2) Codebase track (`codebase/`)
+
+#### Existing: `codebase/mechanisms/00-intro.md` (patch)
+1. What counts as a mechanism
+2. Mechanism class skeleton
+3. `init` vs `loop`
+4. HardwareMap mapping best practices
+5. Servo/motor constants and naming
+6. Basic button mapping pattern
+7. Small updates for clarity and style consistency
+
+#### Existing: `codebase/mechanisms/01-robot-scoring.md` (patch)
+1. Why `Scoring` exists (coordination layer)
+2. State-based logic pattern
+3. `Robot` as composition root
+4. Button behavior in different states
+5. Automation boundaries (manual vs automatic actions)
+6. Add cautionary notes around blocking behavior and race conditions
+
+#### New: `codebase/mechanisms/02-mechanism-design.md`
+1. How to decide if code belongs in a mechanism
+2. Single responsibility in robot components
+3. Interface design for mechanism APIs
+4. Initialization order and dependencies
+5. Safety defaults and fail-safe positions
+6. Testing mechanism logic with dev opmodes
+
+#### New: `codebase/teleop/00-teleop-architecture.md`
+1. TeleOp goals (driver speed + reliability)
+2. Loop structure and update order
+3. Controls abstraction (`Controls.java`-style patterns)
+4. Click vs hold vs toggle inputs
+5. State machine pattern for scoring flow
+6. Telemetry priorities during matches
+
+#### New: `codebase/teleop/01-controls-and-input.md`
+1. Mapping controls for driver + operator
+2. Debouncing and edge detection
+3. Shared buttons with state-dependent behavior
+4. Avoiding input conflicts
+5. Example control map template
+
+#### New: `codebase/commands/00-command-basics.md`
+1. What a command is in team architecture
+2. Why commands reduce TeleOp complexity
+3. Command lifecycle (start/update/finish)
+4. Basic command examples
+5. When *not* to use commands
+
+#### New: `codebase/commands/01-command-sequences.md`
+1. Sequencing actions safely
+2. Interruptions and cancel behavior
+3. Timeout/failure handling
+4. Integrating with state machine logic
+5. Debugging command flow
+
+#### New: `codebase/commands/02-common-bugs.md`
+1. Known pitfalls (including autocommandmachine bug note from planning)
+2. How to isolate command bugs
+3. Logging and telemetry strategy for commands
+
+---
+
+### 3) Autonomous + pathing track (`codebase/auton/`)
+
+#### New: `codebase/auton/00-auton-overview.md`
+1. Match strategy constraints (30s, reliability over complexity)
+2. Auton architecture overview
+3. Required subsystem readiness before auton
+
+#### New: `codebase/auton/01-pedro-setup.md`
+1. Why team is using PedroPathing
+2. Installing/including PedroPathing in project
+3. Required project/folder structure
+4. Minimal first path opmode
+5. Comparison note: RoadRunner concepts mapped to Pedro terms
+
+#### New: `codebase/auton/02-localization-and-constants.md`
+1. Robot constants and geometry
+2. Localization basics and sensor assumptions
+3. How to gather/update constants
+4. Versioning/timestamping tuned values
+
+#### New: `codebase/auton/03-tuning-workflow.md`
+1. Pre-tuning checklist (mechanical + battery + field)
+2. Tuning order and rationale
+3. Verifying repeatability
+4. What to retune and when
+
+#### New: `codebase/auton/04-path-building.md`
+1. Constructing trajectories/paths in PedroPathing
+2. Path segmentation and event markers/callback points
+3. Reusable path snippets
+4. Debugging bad paths (overshoot, drift, heading error)
+
+#### New: `codebase/auton/05-auton-control-flow.md`
+1. Structuring complete autonomous routines
+2. State machine vs command sequence in auton
+3. Integrating scoring mechanism actions with pathing
+4. Failsafes, time budgeting, and fallback parking
+
+#### New: `codebase/auton/06-ftcdashboard-with-auton.md`
+1. Dashboard setup and access
+2. Live constant editing (`@Config`) and safe usage
+3. Telemetry panels for tuning
+4. ADB/IP issues and troubleshooting
+
+#### New: `codebase/auton/07-real-world-failure-modes.md`
+1. Battery voltage effects and mitigation
+2. Slippage/collision recovery behaviors
+3. “Auton went wrong” case studies and postmortem template
+
+---
+
+### 4) FTC Dashboard track (`codebase/ftcdashboard/`)
+
+#### New: `codebase/ftcdashboard/00-intro.md`
+1. What FTC Dashboard is
+2. Team use cases (tuning, telemetry, quick iteration)
+3. Security/practical precautions during practice and competition
+
+#### New: `codebase/ftcdashboard/01-connection-troubleshooting.md`
+1. Network setup basics
+2. Common IP/ADB pitfalls
+3. Quick diagnostics checklist
+
+#### New: `codebase/ftcdashboard/02-telemetry-patterns.md`
+1. High-value telemetry fields
+2. Organizing telemetry by subsystem
+3. Keeping telemetry useful without lag/noise
+
+---
+
+### 5) Misc practical docs (`codebase/misc/`)
+
+#### New: `codebase/misc/00-dev-opmodes.md`
+1. Purpose of dev opmodes
+2. Naming and organization
+3. Safety and cleanup rules
+4. Promotion path from dev test to production code
+
+#### New: `codebase/misc/01-telemetry-best-practices.md`
+1. Driver-station telemetry essentials
+2. Logging for debugging vs match mode
+3. Rate limiting and readability
+
+#### New: `codebase/misc/02-hardware-map-and-config.md`
+1. Hardware naming conventions
+2. Control Hub/Expansion Hub mapping hygiene
+3. Configuration file management between robots
+
+#### New: `codebase/misc/03-ai-usage-guidelines.md`
+1. When AI helps (boilerplate, refactor suggestions)
+2. When AI hurts (blind-copying control logic)
+3. Verification checklist for AI-generated code
+4. Team expectations for attribution/review
+
+---
+
+## Cross-Cutting Documentation Conventions (for Step 2)
+- Every lesson includes:
+  - Objective
+  - Prerequisites
+  - Core concepts
+  - Worked example (small + realistic)
+  - Common mistakes
+  - Quick checklist / “Done when…”
+  - Optional challenge exercise
+- Use consistent vocabulary across lessons (`mechanism`, `Robot`, `Scoring`, `TeleOp`, `Auton`).
+- Keep examples aligned with team style from `power-play/` + `FissionLib` idioms, but modernized to PedroPathing.
+- Prefer simple, maintainable patterns over clever abstractions for newbie readability.
+
+## Planned Patches to Existing Docs (Step 2 scope)
+1. `README.md` — full rewrite as curriculum entry point.
+2. `intro/00-setup.md` — update setup flow + troubleshooting details.
+3. `intro/01-code-overview.md` — replace RoadRunner section with PedroPathing content.
+4. `codebase/mechanisms/00-intro.md` — polish terminology and tighten examples.
+5. `codebase/mechanisms/01-robot-scoring.md` — add stronger guidance on state logic and automation boundaries.
+
+## Open Questions / Info Needed from Team (before or during Step 2)
+1. Current season repository name and exact expected folder structure in `teamcode`.
+2. Whether command framework is currently active and which classes are canonical.
+3. Preferred gamepad mapping standard (Xbox labels vs PS labels).
+4. Exact PedroPathing integration method used by team this season.
+5. Whether electronics lessons should be included now or in a separate track.
+6. Any hard team conventions for branch naming, commit format, and PR checklist.
+
+## Suggested Build Order for Step 2
+1. Rewrite `README.md` (navigation first).
+2. Patch intro files (`intro/00`, `intro/01`).
+3. Patch mechanism docs (`codebase/mechanisms/*`).
+4. Add TeleOp + commands docs.
+5. Add auton/PedroPathing docs.
+6. Add FTC Dashboard + misc docs.
+7. Final pass for consistency and link integrity.

PLANNING.md

@@ -1,12 +1,12 @@
-1. ftc intro - flint
+1. ftc intro
     - [x] download stuff: git, android studio
     - [x] show the org/repo
     - [x] clone repo
     - [x] go through general code structure overview, give names to things
     - [ ] basic mechanism
     - [ ] git tutorial (pretend to push some mechanism code)
     - [ ] basic teleop with controls (no commands yet)
-1. android studio - daniel
+1. android studio
     - [ ] how to set up a project
     - [ ] how to use git with android studio
     - [ ] how to use the FTC SDK
@@ -33,8 +33,7 @@
     - [ ] command sequences
     - [ ] (autocommandmachine has a bug?)
 1. auton
-    - [ ] meep meep
-    - [ ] are we doing rr still?
+    - [ ] set up pedropathing
     - [ ] how to set up the bot and get constants and stuff
     - [ ] how to tune
     - [ ] how to write pathing
@@ -52,9 +51,6 @@
     - [ ] dev op modes
     - [ ] telemetry
 
-and general lesson organization - order of stuff
-install fissionlib and roadrunner stuff
+not yet organized:
+how to install fissionlib and pedropathing
 some instructions about using ai (when to not use and how to use copilot)
-add homeworks
-
-read old stuff and check if anything can be reused