Add open source docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report incorrect behavior in a package
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Package
+
+Which package(s) are affected? (e.g., `pq-oid`, `pq-key-encoder`)
+
+**Language**: TypeScript / Rust
+
+**Version**:
+
+## Description
+
+What happened?
+
+## Expected Behavior
+
+What should have happened?
+
+## Steps to Reproduce
+
+```
+<code or commands to reproduce>
+```
+
+## Environment
+
+- OS:
+- Runtime version (Bun/Node/Rust):
+- Package version:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Package
+
+Which package(s) does this relate to? (e.g., `pq-oid`, or "new package")
+
+## Description
+
+What would you like to see added or changed?
+
+## Use Case
+
+Why is this needed? What problem does it solve?
+
+## Proposed API (optional)
+
+```
+<sketch of the API you'd like to use>
+```
+
+## Additional Context
+
+Any relevant links to RFCs, NIST specs, or related implementations.

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do? Keep it brief. -->
+
+## Package(s)
+
+<!-- Which package(s) are modified? -->
+
+## Languages
+
+- [ ] TypeScript
+- [ ] Rust
+
+## Checklist
+
+- [ ] Tests pass for all modified packages
+- [ ] Linting/formatting passes (`biome check`, `cargo fmt`)
+- [ ] Both language implementations are consistent (or noted as follow-up)
+- [ ] Package README updated if public API changed
+- [ ] No unnecessary dependencies added
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Closes #456 -->

CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to providing a welcoming and productive environment for everyone who contributes to or interacts with this project, regardless of experience level, background, or identity.
+
+## Standards
+
+**Expected behavior:**
+
+- Be respectful and constructive in discussions and code reviews
+- Focus on technical merit
+- Accept constructive feedback
+- Credit others' work and ideas
+
+**Unacceptable behavior:**
+
+- Harassment, insults, or personal attacks
+- Publishing others' private information
+- Trolling or deliberately disruptive behavior
+- Any conduct that would be considered inappropriate in a professional setting
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, issues, and other contributions that violate this code of conduct. Repeat violations may result in a temporary or permanent ban from the project.
+
+## Reporting
+
+Report unacceptable behavior to **conduct@multivmlabs.com**. All reports will be reviewed and handled confidentially.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,200 @@
+# Contributing to post-quantum-packages
+
+Thanks for your interest in contributing. This project provides post-quantum cryptography building blocks used in production blockchain systems, so correctness and consistency matter.
+
+## Before You Start
+
+**For non-trivial changes** (new features, API changes, new packages), please open an issue or start a discussion first. This prevents wasted effort and helps us align on the approach before you write code.
+
+**For bug fixes and small improvements**, feel free to open a PR directly.
+
+## Getting Started
+
+### Prerequisites
+
+You'll need both toolchains to work across the full monorepo. If you're contributing to a single language, you only need that toolchain.
+
+| Language | Runtime | Minimum Version | Tools |
+|----------|---------|-----------------|-------|
+| TypeScript | [Bun](https://bun.sh) | 1.0+ | — |
+| Rust | [rustup](https://rustup.rs) | 1.78+ | `rustfmt`, `clippy` |
+
+### Setup
+
+```bash
+git clone https://github.com/multivmlabs/post-quantum-packages.git
+cd post-quantum-packages
+
+# TypeScript
+bun install
+
+# Rust
+cargo build
+```
+
+### Running Tests
+
+```bash
+# All TypeScript packages
+npm test
+
+# All Rust packages
+cargo test
+
+# Single package (any language)
+cd packages/<package>/ts && bun test
+cd packages/<package>/rust && cargo test
+```
+
+## Package Structure
+
+Every package follows the same dual-language layout:
+
+```
+packages/<package>/
+├── ts/              # TypeScript implementation
+│   ├── package.json
+│   ├── tsconfig.json
+│   ├── src/
+│   ├── tests/
+│   └── README.md
+├── rust/            # Rust implementation
+│   ├── Cargo.toml
+│   ├── src/
+│   └── README.md
+└── test-data/       # Shared test vectors (some packages)
+```
+
+**Cross-language consistency**: Both implementations of a package must expose the same public API and produce identical outputs for the same inputs. Shared test vectors in `test-data/` help enforce this.
+
+## Coding Standards
+
+### TypeScript
+
+- **Formatter/Linter**: [Biome](https://biomejs.dev) (configured in root `biome.json`)
+- **Target**: ES2022, ESNext modules, strict mode
+- **Style**: No `any` types. Explicit return types preferred. Single quotes, semicolons, trailing commas.
+
+```bash
+cd packages/<package>/ts
+bunx biome check --write .   # Format + lint
+bun run build                # Must compile cleanly
+bun test                     # Must pass
+```
+
+### Rust
+
+- **Edition**: 2021
+- **MSRV**: 1.78
+- **Linting**: `clippy` with warnings as errors
+- **Formatting**: `rustfmt`
+- **`no_std`**: Crates must compile with `--no-default-features` where applicable
+
+```bash
+cd packages/<package>/rust
+cargo fmt -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+cargo build --no-default-features
+```
+
+## Implementation Guidelines
+
+This code is used in a **blockchain context** where correctness and efficiency are critical:
+
+- **Minimize allocations** on hot paths (encoding/decoding)
+- **Prefer two-pass encode**: compute total size first, then write directly to the output buffer — no intermediate allocations
+- **Use zero-copy** (`&[u8]` borrowing, `Uint8Array` views) on decode paths where possible
+- **Match raw bytes** over string intermediates (e.g., OID lookup by DER bytes, not dotted-decimal strings)
+- **No unnecessary dependencies**: keep packages lean. Every dependency is attack surface.
+
+## Making Changes
+
+### 1. Fork and Branch
+
+```bash
+git checkout -b feat/pq-oid-add-new-algorithm
+```
+
+Branch naming: `feat/<package>-<description>`, `fix/<package>-<description>`, or `docs/<description>`.
+
+### 2. Make Your Changes
+
+- If you're modifying behavior, update both language implementations to keep them in sync
+- If you're adding a feature to one language, note in the PR that the other language needs corresponding changes
+- Add or update tests for any behavior changes
+- Update the package README if the public API changes
+
+### 3. Verify Locally
+
+Run the checks that CI will run:
+
+```bash
+# TypeScript
+cd packages/<package>/ts
+bunx biome check --write .
+bun run build
+bun test
+
+# Rust
+cd packages/<package>/rust
+cargo fmt -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+### 4. Commit
+
+Use [Conventional Commits](https://www.conventionalcommits.org). The scope should be the package name:
+
+```
+feat(pq-oid): add SLH-DSA-SHA2-128s algorithm support
+fix(pq-key-encoder): correct PKCS#8 version field encoding
+docs(pq-jws): update usage examples for v2 API
+test(pq-cert-verify): add chain validation edge cases
+refactor(pq-spki): reduce allocations in encode path
+```
+
+### 5. Open a Pull Request
+
+- Keep PRs focused — one logical change per PR
+- Fill out the [PR template](.github/pull_request_template.md)
+- Link any related issues
+- CI must pass before review
+- PRs are squash-merged into `main`
+
+## Pull Request Review
+
+PRs are reviewed for:
+
+1. **Correctness** — Does it produce the right output? Are edge cases handled?
+2. **Consistency** — Do both language implementations agree?
+3. **Performance** — No unnecessary allocations or copies on hot paths
+4. **Standards compliance** — Does it follow the relevant RFCs and NIST specifications?
+5. **Test coverage** — Are there tests for new behavior and edge cases?
+6. **Minimal dependencies** — Does it introduce new external dependencies? If so, why?
+
+## Reporting Issues
+
+- **Bugs**: Open a [GitHub issue](https://github.com/multivmlabs/post-quantum-packages/issues/new?template=bug_report.md) with reproduction steps
+- **Security vulnerabilities**: See [SECURITY.md](SECURITY.md) — do **not** open public issues
+- **Feature requests**: Open a [GitHub issue](https://github.com/multivmlabs/post-quantum-packages/issues/new?template=feature_request.md) describing the use case
+
+## Release Process
+
+Versions are bumped using the version script, which creates a git tag that triggers CI publishing:
+
+```bash
+bun run scripts/version <package>/<language> <major|minor|patch>
+# Example: bun run scripts/version pq-oid/ts patch
+```
+
+Tag patterns trigger the corresponding publish workflow:
+- `*/ts@*` → npm publish
+- `*/rust@*` → cargo publish
+
+Only maintainers can publish releases. Contributors do not need to bump versions — this is handled during merge.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present MultiVM Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.