docs: improve OSS readiness basics

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report incorrect behavior, broken analysis, or regressions
+labels: bug
+---
+
+## Summary
+
+Describe the bug clearly.
+
+## Reproduction
+
+- command or MCP tool used:
+- target codebase shape:
+- exact input:
+- expected result:
+- actual result:
+
+## Environment
+
+- package version:
+- node version:
+- OS:
+
+## Validation
+
+Include logs, JSON output, screenshots, or minimal repro files when possible.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Propose a new capability or improvement
+labels: enhancement
+---
+
+## Problem
+
+What problem are you trying to solve?
+
+## Proposed change
+
+Describe the feature or improvement.
+
+## CLI / MCP impact
+
+If relevant, describe:
+- CLI commands or flags affected
+- MCP tools or output shape affected
+- docs that would need updates
+
+## Alternatives considered
+
+List simpler alternatives if any.

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+- 
+
+## Why
+- 
+
+## Changes
+- 
+
+## Validation
+- [ ] lint
+- [ ] typecheck
+- [ ] build
+- [ ] test
+
+## Docs impact
+- [ ] README updated
+- [ ] docs/ updated
+- [ ] no docs changes needed

.gitignore

@@ -7,5 +7,6 @@ next-env.d.ts
 .npmrc
 .mcp.json
 .worktrees/
+.vllnt/
 test-results/
 scripts/

CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our commitment
+
+We want this project to be open, respectful, and useful to contributors of different backgrounds and experience levels.
+
+## Expected behavior
+
+Examples of positive behavior:
+- be respectful and constructive
+- assume good intent
+- give actionable technical feedback
+- keep discussions focused on the work
+- accept correction gracefully
+
+## Unacceptable behavior
+
+Examples of unacceptable behavior:
+- harassment or personal attacks
+- discriminatory language or behavior
+- bad-faith trolling or deliberate disruption
+- doxxing or sharing private information without permission
+- repeated hostile or unconstructive review behavior
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, issues, pull requests, or other contributions that violate this code of conduct.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, contact the maintainers privately when possible.
+For security-sensitive matters, use [SECURITY.md](SECURITY.md).
+
+## Scope
+
+This code of conduct applies in project spaces, including issues, pull requests, discussions, and review conversations.

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thanks for contributing to `codebase-intelligence`.
+
+## Development setup
+
+```bash
+git clone https://github.com/bntvllnt/codebase-intelligence.git
+cd codebase-intelligence
+pnpm install
+```
+
+Useful commands:
+
+```bash
+pnpm dev
+pnpm lint
+pnpm typecheck
+pnpm build
+pnpm test
+```
+
+## Workflow
+
+- Create a feature branch from `main`
+- Keep changes focused and atomic
+- Prefer one concern per pull request
+- Open a PR early if you want feedback on scope
+
+## Commit conventions
+
+This repository uses conventional-style commit subjects.
+
+Examples:
+- `feat: add module-depth CLI command`
+- `fix: normalize Windows paths in MCP handlers`
+- `docs: clarify MCP setup`
+- `test: add regression coverage for dead exports`
+
+The release workflow generates changelog sections from commit prefixes, so prefer:
+- `feat:` for user-visible features
+- `fix:` for user-visible fixes
+- `docs:` / `test:` / `chore:` for non-feature work
+
+## Testing expectations
+
+Before opening a PR, run:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm build
+pnpm test
+```
+
+Testing guidance:
+- prefer real integration coverage over isolated mocking
+- add regression tests for bug fixes
+- update docs when CLI, MCP, or metrics behavior changes
+
+## Pull requests
+
+Please include:
+- what changed
+- why it changed
+- any CLI or MCP surface changes
+- validation performed
+
+If your change affects users, update the relevant docs in `docs/` and `README.md`.
+
+## Security
+
+Do not open public issues for suspected vulnerabilities.
+See [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

README.md

@@ -48,6 +48,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 - [Requirements](#requirements)
 - [Limitations](#limitations)
 - [Release](#release)
+- [Security](#security)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -233,9 +234,23 @@ Publishing is automated through GitHub Actions.
 
 No PAT is required for npm publish. The workflow uses GitHub repository permissions for tagging and OIDC for npm publishing.
 
+## Security
+
+Please do not report security vulnerabilities in public issues.
+
+- Read [`SECURITY.md`](SECURITY.md) for supported versions and disclosure guidance.
+- Use GitHub Security Advisories or private maintainer contact for sensitive reports.
+
 ## Contributing
 
-Contributions are welcome. Please open an issue first to discuss what you'd like to change.
+Contributions are welcome.
+
+Start here:
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, workflow, testing, and PR expectations
+- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — community standards
+- [`SECURITY.md`](SECURITY.md) — vulnerability reporting
+
+Quick setup:
 
 ```bash
 git clone https://github.com/bntvllnt/codebase-intelligence.git

SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are supported for the latest published release on the `main` line.
+
+| Version | Supported |
+|---------|-----------|
+| latest release | yes |
+| older releases | no |
+| prerelease / canary | best effort |
+
+## Reporting a vulnerability
+
+Please do not report vulnerabilities in public GitHub issues.
+
+Use one of these private channels:
+- GitHub Security Advisories for this repository
+- direct maintainer contact if a private channel is available
+
+When reporting, include:
+- affected version
+- impact summary
+- reproduction steps or proof of concept
+- suggested mitigation if known
+
+You can expect:
+- acknowledgement as soon as practical
+- triage and severity assessment
+- a coordinated fix/release plan when confirmed
+
+## Scope
+
+This project analyzes local TypeScript codebases and exposes results through CLI and MCP interfaces.
+Security-relevant reports may include:
+- command execution risks
+- unsafe path handling
+- unintended filesystem access
+- data exposure through MCP responses
+- dependency vulnerabilities with practical impact