From 46d3c5562edb37e2c9ac649d0f2c485aa9374e90 Mon Sep 17 00:00:00 2001
From: bntvllnt <32437578+bntvllnt@users.noreply.github.com>
Date: Thu, 30 Apr 2026 01:13:36 +0200
Subject: [PATCH] docs: improve OSS readiness basics

---
 .github/ISSUE_TEMPLATE/bug_report.md      | 27 ++++++++
 .github/ISSUE_TEMPLATE/feature_request.md | 24 +++++++
 .github/pull_request_template.md          | 19 ++++++
 .gitignore                                |  1 +
 CODE_OF_CONDUCT.md                        | 36 +++++++++++
 CONTRIBUTING.md                           | 78 +++++++++++++++++++++++
 README.md                                 | 47 ++++++++++----
 SECURITY.md                               | 40 ++++++++++++
 8 files changed, 258 insertions(+), 14 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 .github/pull_request_template.md
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..7e3c221
--- /dev/null
+++ b/.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.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..b272939
--- /dev/null
+++ b/.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.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..ffdaf55
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 424d77d..e36a717 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,5 +7,6 @@ next-env.d.ts
 .npmrc
 .mcp.json
 .worktrees/
+.vllnt/
 test-results/
 scripts/
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..e0b71ee
--- /dev/null
+++ b/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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a7b027b
--- /dev/null
+++ b/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).
diff --git a/README.md b/README.md
index b4c7bda..35fbb6e 100644
--- a/README.md
+++ b/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)
 
@@ -207,30 +208,48 @@ codebase-intelligence <command> <path>
 
 ## Release
 
-Publishing is automated and **only happens on `v*` tags**.
+Publishing is automated through GitHub Actions.
 
-### One-time setup
+### Normal CI
 
-1. Create an npm automation token (npmjs.com → Access Tokens).
-2. Add it to GitHub repository secrets as `NPM_TOKEN`.
+- `CI` runs on every PR and push to `main`:
+  - lint → typecheck → build → test
 
-### Normal CI (before release)
+### Canary publish
 
-- `CI` workflow runs on every PR and push to `main`:
-  - lint → typecheck → build → test
+- Pushes to `main` trigger the `Publish` workflow canary job.
+- The package is published to npm with a `canary` tag using the current version plus the short commit SHA.
+
+### Release publish
+
+- Releases are created with the `Publish` workflow via `workflow_dispatch`.
+- Select the bump type: `patch`, `minor`, or `major`.
+- The workflow:
+  1. runs quality gates
+  2. bumps `package.json`
+  3. commits and tags the release
+  4. publishes to npm with provenance
+  5. creates a GitHub Release
 
-### Create a release
+See `.github/workflows/publish.yml` for the exact release flow.
 
-1. Bump `package.json` version.
-2. Commit: `chore(release): bump to vX.Y.Z`
-3. Tag: `git tag vX.Y.Z`
-4. Push: `git push origin main --tags`
+## Security
 
-The `v*` tag triggers the `CI` workflow publish job (`npm publish --access public --provenance`).
+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
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..136d69f
--- /dev/null
+++ b/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