add gitHub community files for contributors and AI-assisted development

AI_POLICY.md

@@ -0,0 +1,40 @@
+# AI Usage Policy
+
+Dimensional is an agent-native project. The whole point of dimOS is that you can "vibecode" robots in natural language, and we build the system itself with heavy AI assistance. **We are not an anti-AI project. Quite the opposite.**
+
+This policy exists for one reason. Contributing to dimOS carries a quality and safety bar that simply using dimOS does not. The code here moves real hardware. The problem we are guarding against is not AI tools. It is contributions where no human actually understands the code. So please read and follow these rules.
+
+## The Rules
+
+- **Disclose all AI usage**
+If AI assisted your contribution in any form, say so. Name the tool (for example Claude Code, Cursor, Codex, or Copilot) and describe how much it was involved. A one-line note in the PR or issue is enough.
+
+- **You must fully understand your PR**
+If you cannot explain what your code changes do and how they interact with the rest of the system without the aid of an AI tool, do not submit them. Feel free to *gain* that understanding by interrogating an agent with access to the codebase before contributing.
+
+- **Hardware changes demand extra scrutiny**
+Control loops, motor drivers, planners, and anything that produces motion can damage equipment or hurt people. AI-assisted changes to these areas must be understood line by line and tested in simulation or replay before any hardware claim is made. See the safety section of [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+- **Issues and discussions may use AI, but a human must review and edit the output**
+AI tends to be verbose and to pad text with noise. Do your own research, trim it down, and write in your own voice, especially for feature proposals and bug reports.
+
+- **No AI-generated media**
+Text and code are the only acceptable AI-generated contributions. Please do not submit AI-generated art, images, video, audio, or diagrams.
+
+## Using dimOS vs Contributing to dimOS
+
+It is worth being explicit, because dimOS lives on both sides of this line.
+
+- **Go wild with AI while using dimOS -** Vibecode your robot, point your favorite agent at [`AGENTS.md`](AGENTS.md), generate skills and blueprints in natural language, and let an LLM drive the CLI and MCP tools. This is the product working as intended.
+
+- **Contributing to dimOS must be AI-assisted and human-understood -** The same tools are welcome, but the bar is that a human reviews, understands, and stands behind every line going into the shared codebase.
+
+## Maintainers
+
+These rules apply to outside contributions, maintainers may use AI tools at their discretion. They have earned the trust to apply good judgment about when and how.
+
+## Reviews Cost Maintainer Time
+
+Issues, discussions, and pull requests are where your work meets a maintainer's calendar. Low-effort or unreviewed submissions, especially confident-looking code or prose that nobody can explain, move the whole job of verification onto a small team and slow everyone else down.
+
+This policy is about quality and safety on real systems, not about banning useful tools.

CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to Dimensional
+
+Thank you for your interest in contributing to Dimensional. This document describes how to contribute to dimOS, whether you are opening an issue, starting a discussion, or sending a pull request.
+
+Dimensional is a fast-moving, pre-release robotics OS maintained by a small team. We genuinely want your contributions, and a few minutes spent reading this will make the difference between a PR that gets merged and one that goes stale. Thank you ❤️
+
+> [!NOTE]
+> This document covers the process: how to report, propose, and get changes accepted.
+>
+> For the technical mechanics, see [`AGENTS.md`](AGENTS.md). That covers building, testing, and running dimOS, the repo layout, the module and blueprint system, code style, the git workflow, and how to add a skill. The two documents are meant to be read together.
+
+## Table of contents
+
+- [The critical rule](#the-critical-rule)
+- [AI usage](#ai-usage)
+- [Safety first](#safety-first)
+- [First-time contributors](#first-time-contributors)
+- [Issues vs. discussions](#issues-vs-discussions)
+- [How to](#how-to)
+- [Contributor License Agreement](#contributor-license-agreement)
+- [Code of conduct](#code-of-conduct)
+
+## The critical rule
+
+**You must understand what you submit.** This is the one rule we will not bend on.
+
+dimOS moves real hardware. A single misunderstanding in a control loop or a driver can crash a quadruped, damage an arm, or send a drone off course. The cost of a change you do not fully grasp is not a failed test. It is broken equipment or someone getting hurt.
+
+So before you open a pull request, make sure you can explain what your change does and how it fits into the rest of the system in your own words. If you cannot do that without leaning on an AI tool, the change is not ready. Writing code with AI is fine and often encouraged. Shipping code you have not reasoned through yourself is not.
+
+## AI usage
+
+dimOS is an agent-native project. Our entire premise is that you can "vibecode" robots in natural language, and we build with AI tools every day. AI is welcome here.
+
+That said, contributing to dimOS has a quality bar that using dimOS does not. We have a short, clear policy covering disclosure and the human-in-the-loop requirement. Please read it before contributing: [AI Usage Policy](AI_POLICY.md). This is important.
+
+## Safety first
+
+> [!WARNING]
+> Read this section if your change touches hardware.
+
+dimOS controls physical robots. Contributions that affect control loops, motor drivers, planners, or anything that can produce motion carry real-world risk.
+
+- **Test in simulation or replay before hardware.** Most subsystems can be exercised with `dimos --simulation run ...` or `dimos --replay run ...` with no robot attached. Use these first.
+- **Never submit untested motion, control, or driver changes.** If you tested on real hardware, say which robot, which firmware, and what you observed in the PR description. If you could not test on hardware, say so explicitly.
+- **Default to caution.** When in doubt about the safety implications of a change, open a discussion before writing code, or ask in [Discord](https://discord.gg/dimos).
+
+## First-time contributors
+
+We want people to use Dimensional, learn it, and help us building it. You do not need robotics hardware or prior experience with every part of the stack to make a useful contribution.
+
+**Start here.**
+Browse [open issues labeled `good first issue`](https://github.com/dimensionalOS/dimos/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). These are scoped tasks that maintainers have marked as approachable for newcomers. Pick one, read the description, and comment if you want to work on it or need clarification. Maintainers are happy to point you in the right direction.
+
+**Get set up.**
+Follow [`AGENTS.md`](AGENTS.md) for install (`uv sync --extra all`), running blueprints in simulation or replay, and the test workflow (`uv run pytest`). Most changes can be developed and validated without a physical robot.
+
+**This still applies to you.**
+The [critical rule](#the-critical-rule) and [AI policy](AI_POLICY.md) apply to everyone. Use AI tools if they help you learn the codebase, but understand what you submit. Link your PR to the issue you are working on.
+
+## Issues vs Discussions
+
+We keep a clean separation so maintainers can find work that is actually ready.
+
+- The **issue tracker is for actionable, accepted work.** Every open issue should be something a contributor can pick up and start on.
+- **Discussions are for everything else.** This includes bug reports that need triage, feature ideas, design questions, and Q&A. Once a discussion produces a well-scoped, agreed-upon task, a maintainer promotes it to an issue.
+
+This means most contributions start as a discussion, not an issue or a PR.
+
+## How to report a bug:
+
+1. Search [existing issues](https://github.com/dimensionalOS/dimos/issues) and [discussions](https://github.com/dimensionalOS/dimos/discussions) first, including closed ones. Your bug may already be known or fixed.
+2. If it is new, open a discussion describing the problem. Include your OS, install method (`uv`, Nix, Docker), the robot or blueprint involved, the exact command you ran, and the full error or unexpected behavior.
+3. If an open issue or discussion already matches, do not add a "+1" comment, use an emoji reaction or the upvote button instead. Comments notify everyone subscribed. Reactions do not.
+
+### Propose a feature
+
+1. Search issues and discussions to make sure it has not been proposed already.
+2. Open a **discussion** in the feature or ideas category describing what you want and why. Keep it focused.
+3. If maintainers accept it, it becomes an issue. That is your green light to implement.
+
+## How to submit a pull request:
+
+1. **PRs should map to an accepted issue:** If you open a PR for something that was not discussed and accepted first, it may sit unreviewed or be closed. This is not because the idea is bad, but because unscoped PRs are expensive to review. When in doubt, open a discussion and link your branch.
+2. **Sign the CLA:** All contributions require a signed [Contributor License Agreement](CLA.md). See [Contributor License Agreement](#contributor-license-agreement) below.
+3. **Follow the build and style conventions in [`AGENTS.md`](AGENTS.md):** Use branch prefixes (`feat/`, `fix/`, `docs/`, and so on), target `main`, run the fast test suite (`uv run pytest`), pass pre-commit, and do not force-push or spam pushes. Every push triggers roughly an hour of CI.
+4. **Fill out the PR description template:** GitHub pre-fills it when you open the pull request. Do not clear it. Complete every section:
+
+   - Problem: What is broken or missing.
+   - Solution: What your change does.
+   - How to Test: The sim, replay, or hardware steps a reviewer can follow.
+   - AI assistance: What was AI-assisted, as required by the [AI policy](AI_POLICY.md).
+   - CLA checkbox: Confirm you have signed.
+
+   If you strip out the template, maintainers may close the PR without reviewing it.
+5. **PRs are not the place to debate design.** If a feature needs discussion, use a discussion and link your branch.
+
+### Ask a question
+
+Open a Q&A discussion, or join the [Discord](https://discord.gg/dimos) and ask in the help channel. Questions do not need the detail a bug report does.
+
+## Contributor License Agreement
+
+dimOS is developed by Dimensional Inc. Before your first contribution can be merged, you will need to sign our [Contributor License Agreement](CLA.md). It clarifies the IP license you are granting and protects both you and the project. It does not take away your right to use your own work elsewhere. The signing prompt will appear on your first pull request.
+
+## Code of conduct
+
+Be respectful. There are humans on the other side of every issue, discussion, and review. Low-effort or hostile contributions put the burden of cleanup on a small team, so please do not create them. We are happy to help newcomers learn and grow. Meet us halfway with effort and good faith.
+
+---
+
+Thanks for helping build the operating system for physical space. We are glad you are here.