chore: professionalize repository governance and presentation

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{md,mdx}]
+trim_trailing_whitespace = false
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{js,jsx,ts,tsx,json,yml,yaml,css,scss}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Default reviewer for repository changes.
+* @CognitiveCodeAI
+
+# High-assurance areas.
+/backend/app/acl/ @CognitiveCodeAI
+/backend/app/auth/ @CognitiveCodeAI
+/backend/app/qa/ @CognitiveCodeAI
+/backend/app/services/highlighting.py @CognitiveCodeAI
+/backend/alembic/ @CognitiveCodeAI
+/.github/ @CognitiveCodeAI

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: Bug report
+description: Report reproducible behavior that is not working as expected
+title: "[bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve NPR. Do not include client documents, credentials, personal data, protected health information, or privileged legal material.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the problem and its impact.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Provide the smallest safe reproduction you can.
+      placeholder: |
+        1. Start the stack with ...
+        2. Upload or query a synthetic document ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - Ingestion or parsing
+        - Retrieval or ranking
+        - Answer generation or citations
+        - Evidence highlighting
+        - ACL, authentication, or tenant isolation
+        - Frontend
+        - Infrastructure or deployment
+        - Documentation
+        - Not sure
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include OS, Python, Node, browser, deployment type, and relevant service versions.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Sanitized logs or screenshots
+      description: Redact secrets and sensitive document content.
+      render: text
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed secrets, private documents, and personal or regulated data.
+          required: true
+        - label: This is not a security vulnerability. Security reports belong in a private advisory.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and usage help
+    url: https://github.com/CognitiveCodeAI/rag-main-2/discussions
+    about: Use Discussions for setup help, architecture questions, and show-and-tell.
+  - name: Report a security vulnerability privately
+    url: https://github.com/CognitiveCodeAI/rag-main-2/security/advisories/new
+    about: Do not disclose vulnerabilities in a public issue.
+  - name: Commercial support
+    url: https://cognitivecode.ai
+    about: Contact Cognitive Code for implementation and commercial support.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Propose an improvement grounded in a concrete user need
+title: "[idea]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the workflow, user, and current limitation.
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe observable behavior rather than only an implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Note workarounds or designs you evaluated.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Primary area
+      options:
+        - Ingestion or parsing
+        - Retrieval or ranking
+        - Answer generation or citations
+        - Evidence highlighting
+        - ACL, authentication, or tenant isolation
+        - Frontend
+        - Infrastructure or operations
+        - Documentation or developer experience
+    validations:
+      required: true
+  - type: textarea
+    id: safety
+    attributes:
+      label: Safety, privacy, and compatibility considerations
+      description: Identify effects on sensitive documents, permissions, provenance, APIs, migrations, or existing deployments.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Success criteria
+      description: Explain how this feature should be tested or measured.
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,42 @@
+## What changed?
+
+Describe the user-visible and technical changes.
+
+## Why?
+
+Explain the problem, motivation, and linked issue (`Closes #123`) where applicable.
+
+## Risk and safety
+
+- What can fail?
+- Does this affect ACLs, authentication, tenant isolation, citations, provenance, highlighting, migrations, external APIs, or stored data?
+- What is the rollback path?
+
+## Validation
+
+- [ ] Relevant backend tests pass.
+- [ ] Frontend tests, lint, type checking, and build pass when applicable.
+- [ ] Integration tests cover affected service boundaries.
+- [ ] Migrations were rehearsed in both directions when applicable.
+- [ ] Documentation and configuration examples are updated.
+- [ ] No secrets, client documents, personal data, or generated sensitive artifacts are included.
+
+List exact commands and results:
+
+```text
+commands and results
+```
+
+## Evidence-sensitive checklist
+
+Complete when the change affects answers or source review:
+
+- [ ] Unsupported claims fail closed or abstain.
+- [ ] Citations resolve only to authorized packed context.
+- [ ] Wrong document, version, page, hash, or quote cannot be labeled verified.
+- [ ] Approximate or unavailable evidence is clearly distinguished.
+- [ ] Representative single-hop and multi-hop behavior was checked.
+
+## Notes for reviewers
+
+Call out the files, decisions, tradeoffs, or follow-up work that deserve extra attention.

.github/workflows/ci.yml

@@ -4,14 +4,20 @@ on:
   push:
     branches: ["main", "master"]
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   backend-quality:
     name: Backend Quality
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     steps:
       - name: Checkout
@@ -48,6 +54,7 @@ jobs:
   backend-integration:
     name: Backend Integration (security gate)
     runs-on: ubuntu-latest
+    timeout-minutes: 30
 
     # Pin the connection config to the docker-compose defaults so the job does
     # not depend on a backend/.env (absent in CI) or any ambient runner env.
@@ -96,7 +103,8 @@ jobs:
       - name: Initialize databases and storage
         working-directory: backend
         run: |
-          export PATH="$(python -c 'import sys,os;print(os.path.dirname(sys.executable))'):$PATH"
+          python_bin_dir="$(python -c 'import sys,os;print(os.path.dirname(sys.executable))')"
+          export PATH="${python_bin_dir}:$PATH"
           python -m scripts.setup.setup_postgres
           python -m scripts.setup.setup_minio
           python -m scripts.setup.setup_milvus
@@ -125,6 +133,7 @@ jobs:
   frontend-quality:
     name: Frontend Quality
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     steps:
       - name: Checkout
@@ -160,6 +169,7 @@ jobs:
   dependency-audit:
     name: Dependency Audit (non-blocking)
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     continue-on-error: true
 
     steps:

.gitignore

@@ -144,5 +144,10 @@ test docs/
 openapi.json
 nul
 
+# Local evaluation, browser, and research artifacts
+/output/
+/tmp/
+/.playwright-cli/
+
 # Claude Code local settings (machine-specific)
 .claude/settings.local.json

CHANGELOG.md

@@ -14,10 +14,17 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
   - `CONTRIBUTING.md`
   - `SECURITY.md`
   - `.github/workflows/ci.yml`
+- Professional repository governance:
+  - Code of Conduct, support, maintainer, and release guides
+  - structured bug and feature issue forms
+  - pull-request template and CODEOWNERS
+  - EditorConfig for consistent cross-platform formatting
 
 ### Changed
 
 - CI now validates backend unit tests and frontend lint/build on pull requests and pushes to default branches.
+- CI now supports manual runs, cancels superseded branch runs, and applies job timeouts.
+- README now presents verified setup requirements, project status, CI badges, navigation, and community links.
 
 ## [1.0.0] - YYYY-MM-DD
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+NPR adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its Code of Conduct.
+
+We are committed to a welcoming, respectful, and harassment-free community for everyone, regardless of background, identity, experience level, or area of expertise. Be constructive, assume good faith, and remember that this project handles software intended for evidence-sensitive workflows.
+
+## Expected behavior
+
+- Communicate respectfully and focus criticism on ideas and code.
+- Welcome questions and help contributors learn the system safely.
+- Protect confidential, personal, legal, clinical, and security-sensitive information.
+- Disclose conflicts of interest that could affect a technical or governance decision.
+- Respect maintainers' decisions about safety, scope, and release readiness.
+
+## Unacceptable behavior
+
+Harassment, discrimination, threats, doxxing, deliberate disclosure of confidential material, sustained disruption, and knowingly unsafe or misleading contributions are not acceptable.
+
+## Enforcement
+
+Report conduct concerns confidentially to [larry@cognitivecode.ai](mailto:larry@cognitivecode.ai). Maintainers will review reports promptly and discreetly and may edit or remove content, reject contributions, restrict participation, or take other proportionate action.
+
+_Attribution: adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1._