docs: add CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README, SECURITY

CODE_OF_CONDUCT.md

@@ -0,0 +1,130 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that promotes a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility, apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported via [GitHub's private reporting channel](https://github.com/ocpp-debugkit/ocpp-debugkit/security/advisories/new).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla-coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla-coc]: https://www.mozilla.org/en-US/about/governance/policies/enforcement/
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to OCPP DebugKit
+
+Thank you for your interest in contributing to OCPP DebugKit! This document
+covers setup, conventions, and the contribution workflow.
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** >= 20.0.0
+- **pnpm** 10.x (`npm install -g pnpm`)
+- **Git**
+
+### Local Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ocpp-debugkit/ocpp-debugkit.git
+cd ocpp-debugkit
+
+# Install dependencies
+pnpm install
+
+# Verify everything works
+pnpm lint
+pnpm test
+pnpm build
+```
+
+## Monorepo Structure
+
+```
+ocpp-debugkit/
+├── packages/
+│   ├── core/          # Data model, parser, normalizer, timeline, failure detection
+│   ├── scenarios/     # Predefined trace scenarios for testing
+│   ├── reporter/      # Report generators (Markdown, HTML)
+│   ├── cli/           # Command-line interface
+│   ├── replay/        # Replay engine (v0.2+)
+│   └── react/         # Reusable React components (v0.2+)
+├── apps/
+│   └── web/           # Single Next.js app (landing, inspector, docs, blog)
+└── ...
+```
+
+See [`AGENTS.md`](./AGENTS.md) for a detailed overview of the architecture,
+build commands, and package dependency graph.
+
+## Development Workflow
+
+### 1. Find or Create an Issue
+
+All work should be tracked via GitHub Issues. Check existing issues or create
+a new one using the appropriate issue template (bug report, feature request,
+or scenario request).
+
+### 2. Create a Branch
+
+```bash
+git checkout -b feat/<scope>-<description>
+```
+
+### 3. Make Your Changes
+
+- Follow the code style (TypeScript strict, Prettier, ESLint).
+- Write tests for the behavior you introduce.
+- Update documentation as needed.
+
+### 4. Verify Locally
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+### 5. Add a Changeset
+
+If your PR changes publishable package behavior, add a changeset:
+
+```bash
+pnpm changeset
+```
+
+This creates a file in `.changeset/` describing the change and which packages
+are affected.
+
+### 6. Open a Pull Request
+
+- Use the PR template.
+- Link the issue with `Closes #N`.
+- Ensure CI passes (lint, typecheck, test, build).
+
+## Conventions
+
+### Commit Messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(core): implement trace parser for JSON input
+fix(cli): handle missing trace file gracefully
+docs: add architecture overview to docs
+chore: add vitest configuration
+test(core): add parser edge case tests
+```
+
+### Branch Naming
+
+```
+feat/<scope>-<description>     # e.g. feat/core-parse-trace
+fix/<scope>-<description>      # e.g. fix/cli-stdout-encoding
+chore/<description>            # e.g. chore/ci-workflow
+docs/<description>             # e.g. docs/readme
+test/<description>             # e.g. test/core-coverage
+```
+
+### Code Style
+
+- **TypeScript strict mode** — no `any` without justification.
+- **Prettier** for formatting (single quotes, trailing commas, 100 char width).
+- **ESLint** with `typescript-eslint` strict rules.
+- Use `import type` for type-only imports.
+
+### Testing
+
+- Tests use **Vitest**.
+- Test files: `*.test.ts` / `*.spec.ts`.
+- Tests live next to the code they test.
+- Coverage target: 70%+ for core package.
+
+## Security Guidelines
+
+OCPP DebugKit processes untrusted input (trace files, pasted content). When
+working on parsing, CLI, or UI code:
+
+- **Validate all external input** — CLI args, file content, paste input.
+- **Safe JSON parsing** — always use try/catch and enforce size limits.
+- **No dynamic code execution** — no `eval()`, `Function()` on untrusted input.
+- **No prototype pollution** — validate object shapes, use safe parsing.
+- **Path safety** — validate file paths, prevent path traversal.
+- **Safe rendering** — no `dangerouslySetInnerHTML`, no unsafe HTML injection.
+- **Browser-local processing** — no automatic uploading of user data.
+- **No secrets in committed files** — no credentials, API keys, or tokens.
+- **No sensitive data in committed artifacts** — use synthetic data in trace
+  fixtures, sample data, and test data. Real station IDs, transaction IDs, IPs,
+  or personal information must not appear in committed files. User-loaded
+  traces and runtime-generated reports are **not** subject to this rule — they
+  contain the user's own data and must not be redacted.
+
+If you discover a security vulnerability, please see the
+[Security Policy](./SECURITY.md) for responsible disclosure.
+
+## AI-Assisted Development
+
+Maintainers may use AI-assisted development tools, but all contributions must
+be reviewed, tested, documented, and scoped like normal engineering work.
+AI-generated code is held to the same standards as any other contribution: it
+must pass CI, include tests, be security-reviewed, and be understandable by a
+human reviewer.
+
+Contributors using AI agents can point them at [`AGENTS.md`](./AGENTS.md) for
+a structured overview of this repository's architecture, conventions, and build
+system. [`CURRENT_STATE.md`](./CURRENT_STATE.md) reflects what has been built
+so far and what is in progress — use it to orient your agent before starting
+work.
+
+No AI tool preference is assumed or required. The project does not endorse any
+specific AI tool.
+
+## Living Documents
+
+The following documents are updated as part of the work, inside the PR:
+
+| Document | When updated |
+|----------|-------------|
+| `CURRENT_STATE.md` | Inside every PR, before merge |
+| `AGENTS.md` | When architecture, packages, or build commands change |
+| `CONTRIBUTING.md` | When contribution process or conventions change |
+| `ROADMAP.md` | At each milestone boundary |
+| `README.md` | When description, badges, quickstart, or links change |
+
+## Questions?
+
+- Open a [GitHub Issue](https://github.com/ocpp-debugkit/ocpp-debugkit/issues)
+- Read the [documentation](https://ocppdebugkit.com/docs)
+- Check the [roadmap](./ROADMAP.md)

CURRENT_STATE.md

@@ -21,7 +21,7 @@ feature code lands.
 - ✅ GitHub labels created (type, package, priority, workflow)
 - ✅ 11 tracking issues created and assigned to M0 milestone
 
-### Monorepo & Tooling (in progress — PR #12)
+### Monorepo & Tooling (PR #12)
 - ✅ Root `package.json` with pnpm workspace
 - ✅ `pnpm-workspace.yaml` (`packages/*`, `apps/*`)
 - ✅ `tsconfig.base.json` (strict TypeScript config)
@@ -32,21 +32,29 @@ feature code lands.
 - ✅ `NOTICE` file (Apache 2.0)
 - ✅ `AGENTS.md` + `CURRENT_STATE.md` (initial versions)
 
-### CI & Release (in progress — this PR)
+### CI & Release (PR #13)
 - ✅ `.github/workflows/ci.yml` — lint, format check, typecheck, test, build on PR + push
 - ✅ `.github/workflows/release.yml` — Changesets version PR, npm publish, ecosystem tag + GitHub release
 - ✅ `.changeset/config.json` — public access, base branch main
 
-### GitHub Templates (in progress — this PR)
+### GitHub Templates (PR #14)
 - ✅ `.github/PULL_REQUEST_TEMPLATE.md`
 - ✅ `.github/ISSUE_TEMPLATE/bug_report.md`
 - ✅ `.github/ISSUE_TEMPLATE/feature_request.md`
 - ✅ `.github/ISSUE_TEMPLATE/scenario_request.md`
 
+### Community Docs (in progress — this PR)
+- ✅ `CONTRIBUTING.md` (setup, conventions, PR process, AI-assisted dev section)
+- ✅ `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)
+- ✅ `ROADMAP.md` (milestone summary)
+- ✅ `README.md` (description, badges, architecture, quickstart, support, links)
+- ✅ `SECURITY.md` (vulnerability reporting, security principles)
 
+## What's Next
 
-1. **PR4** (Issues #9–#11): CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README
-2. **M0 complete** → proceed to M0.5 (Protocol & Trace-Format Design Phase)
+1. **M0 complete** → maintainer reviews and merges PRs #12–#15
+2. Add required status checks to branch protection (after CI runs on main)
+3. Proceed to M0.5 (Protocol & Trace-Format Design Phase)
 
 ## Known Blockers / Decisions Pending