feat: add issue templates and instruction for setup

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,66 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report a bug. Please fill out the sections below so we can reproduce and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce the issue?
+      placeholder: |
+        1. Configure ...
+        2. Run ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages or logs if available.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Relevant environment details.
+      placeholder: |
+        - Project version: v0.1.0
+        - OS: Ubuntu 22.04 / macOS 15 / Windows 11
+        - Runtime/language version (if applicable): Go 1.22 / Node 22 / Python 3.12
+        - Deployment method: Docker Compose / Helm / binary / npm
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or logs that might help.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: mailto:[email protected]
+    about: Do not open a public issue for security vulnerabilities. Email us instead.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,40 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting an improvement. Please describe the feature and why it would be useful.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve? Is it related to a frustration or limitation?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like. How should it work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you've considered.
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, mockups, or references that might help.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,32 @@
+name: Question
+description: Ask a question about usage, configuration, or behavior
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have a question? We're happy to help. Please provide enough detail so we can give a useful answer.
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What would you like to know?
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What are you trying to do? Include your setup, configuration, or use case.
+    validations:
+      required: false
+
+  - type: textarea
+    id: attempted
+    attributes:
+      label: What I've Tried
+      description: Any documentation, searches, or approaches you've already tried.
+    validations:
+      required: false

CLA.md

@@ -1,28 +1,65 @@
 # Contributor License Agreement (CLA)
 
-This Contributor License Agreement ("Agreement") is between you ("Contributor") and the project owner/maintainer ("Maintainer").
+**Version 1.0 — Effective April 2026**
+
+This Contributor License Agreement ("Agreement") is between you ("Contributor") and bitkaio LLC, a Wyoming limited liability company ("Company").
+
+By submitting a Contribution to this project, you accept and agree to the terms of this Agreement. Acceptance is indicated by any of the following: signing via a CLA bot (e.g., CLA Assistant), adding your name to a signature file, or any other method designated by the Company.
 
 ## 1. Definitions
-"Contribution" means any code, documentation, or other material you submit to this repository, including via pull requests, issues, or patches.
 
-## 2. Grant of Rights
-Contributor grants Maintainer a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to:
-- use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the Contribution and derivative works of the Contribution.
+"Contribution" means any code, documentation, or other material you submit to this project, including via pull requests, issues, patches, or any other form of submission.
+
+"Project" means the software project to which the Contribution is made and all associated repositories maintained by the Company.
+
+## 2. Grant of Copyright License
+
+Contributor hereby grants to the Company a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to:
+
+- use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the Contribution and derivative works thereof.
 
-This license allows Maintainer to distribute the Contribution as part of the project under the project's current license **or any future license**, including proprietary licenses.
+The Company may sublicense the Contribution under any terms it chooses, including terms that differ from or are more restrictive than the license under which the Project is currently distributed. This includes, without limitation, the right to distribute the Contribution as part of the Project under any open-source license, proprietary license, or commercial license, whether such license exists now or is created in the future.
 
-## 3. Patent License (optional but recommended)
-Contributor grants Maintainer a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated below) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Contribution, where such license applies only to patent claims licensable by Contributor that are necessarily infringed by the Contribution.
+## 3. Grant of Patent License
 
-If Contributor initiates patent litigation alleging that the Contribution (or the project) infringes a patent, then any patent license granted under this Agreement for that Contribution terminates as of the date such litigation is filed.
+Contributor hereby grants to the Company a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated below) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Contribution, where such license applies only to patent claims licensable by Contributor that are necessarily infringed by the Contribution alone or by combination of the Contribution with the Project to which it was submitted.
+
+If Contributor institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Contribution or the Project constitutes direct or contributory patent infringement, then any patent license granted under this Agreement for that Contribution shall terminate as of the date such litigation is filed.
 
 ## 4. Contributor Representations
+
 Contributor represents that:
-- they have the legal right to grant the licenses in this Agreement; and
-- each Contribution is their original work or they have the right to submit it under these terms.
 
-## 5. No Obligation
-Maintainer has no obligation to include a Contribution in the project.
+(a) they have the legal right to grant the licenses in this Agreement;
+
+(b) each Contribution is their original work, or they have obtained sufficient rights from any third party to submit it under these terms;
+
+(c) if the Contribution is made in the course of employment, or the Contributor's employer has intellectual property rights over the Contribution, the Contributor has received permission from their employer to make the Contribution and grant the licenses in this Agreement, or the Contributor's employer has waived such rights for the Contribution;
+
+(d) they will promptly notify the Company if any of the above representations become inaccurate.
+
+## 5. Entity Contributions
+
+If the Contribution is submitted on behalf of a legal entity (e.g., an employer or organization), the person submitting the Contribution represents that they are authorized to do so and to bind that entity to this Agreement. In that case, "Contributor" refers to the entity, and the individual signing acts as its authorized representative.
+
+## 6. Assignment and Successors
+
+The Company may assign its rights and obligations under this Agreement to any entity that controls, is controlled by, or is under common control with the Company, or to any successor in interest whether by merger, acquisition, reorganization, or transfer of substantially all assets. This Agreement shall be binding upon and inure to the benefit of the parties and their respective successors and assigns.
+
+Contributor may not assign this Agreement without the prior written consent of the Company.
+
+## 7. No Obligation
+
+The Company has no obligation to include any Contribution in the Project.
+
+## 8. Trademarks
+
+This Agreement does not grant Contributor any rights in the Company's trademarks, service marks, trade names, or branding.
+
+## 9. Governing Law
+
+This Agreement shall be governed by and construed in accordance with the laws of the State of Wyoming, without regard to conflict of law principles.
+
+## 10. Entire Agreement
 
-## 6. Miscellaneous
-This Agreement does not grant Contributor any rights in Maintainer trademarks or branding.
+This Agreement constitutes the entire agreement between the parties concerning the subject matter hereof and supersedes all prior agreements and understandings. This Agreement may only be modified by a written amendment signed by both parties.

CONTRIBUTING.md

@@ -1,25 +1,72 @@
-## Issue-first workflow (required)
+# Contributing
 
-All contributions **must be associated with a GitHub Issue**.
+Thank you for your interest in contributing to this project. This guide applies to all repositories maintained by bitkaio LLC.
 
-### Before you start
-- Create a new issue describing the change, or comment on an existing issue to confirm you’re working on it.
-- For small changes (typos, tiny refactors), you can create a lightweight issue labeled `chore`.
+## Contributor License Agreement
 
-### Branch naming
-Create your branch from an issue:
-- `issue/<ISSUE_NUMBER>-short-description`
-  - Example: `issue/123-fix-typo`
+All contributors must agree to the [Contributor License Agreement](CLA.md) before their first contribution can be merged. This is a one-time requirement per contributor.
 
-### Pull Request requirements
-Your Pull Request must:
-- Reference the issue in the PR description using one of:
-  - `Closes #<ISSUE_NUMBER>` (preferred when the PR fully resolves it)
-  - `Refs #<ISSUE_NUMBER>` (when it’s partial or related)
-- Include a short summary of what changed and why.
+When you open your first pull request, a CLA bot will check whether you have signed. If not, it will guide you through the process. Your signature covers all repositories under bitkaio LLC.
 
-### Exceptions (maintainers only)
-Maintainers may merge urgent fixes without a prior issue (e.g., security, production breakages),
-but must open an issue immediately after the merge and link the commit/PR.
+## Getting Started
 
-PRs that are not linked to an issue may be closed without review.
+1. Fork the repository
+2. Create a feature branch from `main` (`git checkout -b feat/your-feature`)
+3. Make your changes
+4. Run the project's tests and linters (see the project README for commands)
+5. Open a pull request against `main`
+
+## Pull Request Guidelines
+
+- Keep PRs focused — one feature, fix, or refactor per PR
+- Write a clear title and description explaining **what** changed and **why**
+- Include tests for new functionality and bug fixes
+- Ensure existing tests pass before submitting
+- Link related issues in the PR description (e.g., `Closes #42`)
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```text
+type(scope): short description
+
+Optional longer explanation.
+```
+
+Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`.
+
+Examples:
+
+- `feat(search): add query expansion support`
+- `fix(scraper): handle timeout on redirect chains`
+- `docs: update configuration reference`
+
+## Code Style
+
+- Follow the conventions already established in the codebase
+- Run the project's linter before submitting (formatting, imports, etc.)
+- Prefer clarity over cleverness
+- Add comments only where the intent isn't obvious from the code
+
+## Reporting Issues
+
+- Use GitHub Issues for bug reports and feature requests
+- For bugs, include: steps to reproduce, expected behavior, actual behavior, and environment details
+- Check existing issues before opening a new one
+
+## Security Vulnerabilities
+
+Do **not** open a public issue for security vulnerabilities. Instead, email [email protected] with a description of the vulnerability. We will respond within 72 hours.
+
+## Code of Conduct
+
+Be respectful and constructive. We expect all contributors to act professionally and treat others with courtesy. Harassment, discrimination, or disruptive behavior will not be tolerated.
+
+## Questions
+
+If you're unsure about anything, open a discussion or issue — we're happy to help.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the terms described in the [CLA](CLA.md). The project's current license is specified in the [LICENSE](LICENSE) file.