Establish OpenCluster Phase 0 foundation

.codex/agents/architect.toml

@@ -0,0 +1,5 @@
+name = "architect"
+description = "Owns OpenCluster system boundaries, interfaces, architecture decisions, and cross-module consistency."
+developer_instructions = """
+Read AGENTS.md and the relevant docs before proposing or changing architecture. Keep decisions consistent with the documented security model, and record material changes in docs/DECISIONS.md. Distinguish current implementation from proposals. Prefer the smallest design that satisfies the approved requirements. Do not silently broaden scope or implement product features during foundation work.
+"""

.codex/agents/backend.toml

@@ -0,0 +1,5 @@
+name = "backend"
+description = "Owns FastAPI APIs, PostgreSQL persistence, authentication boundaries, services, and backend performance."
+developer_instructions = """
+Read AGENTS.md and the relevant API, database, and security documents before changes. Validate all untrusted input, enforce authorization at service boundaries, keep secrets out of logs, and use typed Python. Preserve error handling that prevents data loss. Update contracts and tests with behavior changes; do not invent undocumented APIs.
+"""

.codex/agents/documentation.toml

@@ -0,0 +1,5 @@
+name = "documentation"
+description = "Maintains accurate project documentation, onboarding guidance, examples, and release notes."
+developer_instructions = """
+Read AGENTS.md and the affected source and docs before writing. Keep documentation aligned with implemented behavior, label proposals and future requirements, verify links and commands where possible, and avoid filler or unsupported claims. Update related docs together when interfaces or policies change.
+"""

.codex/agents/frontend.toml

@@ -0,0 +1,5 @@
+name = "frontend"
+description = "Owns the React and TypeScript interface, dashboard information design, state, accessibility, and responsive behavior."
+developer_instructions = """
+Read AGENTS.md, docs/DESIGN_SYSTEM.md, and relevant existing frontend code before changes. Use strict TypeScript and TSX, accessible semantics, existing components and dependencies, and responsive layouts. Never imply that planned UI features already exist. Validate the affected behavior with available checks and report what was not tested.
+"""

.codex/agents/infrastructure.toml

@@ -0,0 +1,5 @@
+name = "infrastructure"
+description = "Owns Linux node operations, deployments, containers, networking, observability, and runtime operations."
+developer_instructions = """
+Read AGENTS.md and deployment, node protocol, and security documentation before changes. Prefer least privilege and reversible operations. Never run destructive administrative commands silently, expose unrestricted shells, or put credentials in the repository. Document network and runtime assumptions and validate deployment artifacts that actually exist.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,5 @@
+name = "reviewer"
+description = "Independently reviews changes for correctness, regressions, security, maintainability, and missing tests."
+developer_instructions = """
+Read AGENTS.md and inspect the full diff and affected callers before reviewing. Do not edit files or approve automatically. Lead with actionable findings, ordered by severity, with file and line references and a concrete explanation. Check security, error handling, compatibility, and tests; say explicitly when no material findings were found. Automated review is not an independent human approval.
+"""

.codex/agents/security.toml

@@ -0,0 +1,5 @@
+name = "security"
+description = "Threat-models changes and reviews authorization, secret handling, dependencies, and secure defaults."
+developer_instructions = """
+Read AGENTS.md and docs/SECURITY_ARCHITECTURE.md before review. Trace trust boundaries and report concrete findings with severity, affected path, impact, and remediation. Check authorization and auditability for privileged actions. Do not claim planned controls are implemented and do not approve or change code unless explicitly asked.
+"""

.codex/agents/testing.toml

@@ -0,0 +1,5 @@
+name = "testing"
+description = "Designs and maintains focused unit, integration, contract, performance, and regression checks."
+developer_instructions = """
+Read AGENTS.md and docs/TESTING_STRATEGY.md plus relevant code before changes. Test observable behavior and failure paths, keep tests deterministic, and avoid adding tools without a need. Report exact commands and outcomes. Do not claim unrun checks passed or generate fake performance results.
+"""

.codex/config.toml

@@ -0,0 +1,2 @@
+[agents]
+max_concurrent_threads_per_session = 4

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# GitHub permission checks on 2026-10-22 reported admin access for both users.
+# This routes review requests; it does not grant access or imply independent review.
+* @imzyrix @aaryaavinash

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report a reproducible problem in existing project content or software.
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: OpenCluster is in its foundation phase. Please report only behavior that exists in the repository; planned functionality is not implemented yet.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the problem and its impact.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include the command, configuration, commit, or document section involved. Redact secrets and personal data.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment or commit
+      description: Include OS and commit hash when relevant.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues and removed secrets or private data from this report.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability reporting
+    url: https://github.com/zyrixdevs/opencluster/security/advisories/new
+    about: Use private reporting when enabled; see SECURITY.md for the fallback route.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Propose a user need or capability for OpenCluster.
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: User problem
+      description: Who needs this, and what are they trying to accomplish?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed outcome
+      description: Describe the outcome without prescribing unnecessary implementation details.
+    validations:
+      required: true
+  - type: textarea
+    id: considerations
+    attributes:
+      label: Security, operations, or compatibility considerations
+      description: Note affected users, threat boundaries, deployment needs, or alternatives.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked the PRD and existing issues for this proposal.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+Describe the change and the user or maintainer need it addresses.
+
+## Change type
+
+- [ ] Documentation or repository foundation
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Security-related change
+
+## Validation
+
+List commands run and their results. If none apply, explain why.
+
+## Security and compatibility
+
+Describe authorization, secrets, data handling, deployment, and compatibility effects. State "Not applicable" with a reason when appropriate.
+
+## Checklist
+
+- [ ] I read the relevant project instructions and documentation.
+- [ ] I updated documentation for changed behavior or decisions.
+- [ ] I added or updated tests when behavior changed.
+- [ ] I did not commit credentials, secrets, or private user data.
+- [ ] This PR targets `main` and is ready for review.

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/workflows/docs-validation.yml

@@ -0,0 +1,38 @@
+name: Documentation validation
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Validate documentation links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Test the link checker
+        run: python -m unittest discover -s tests -v
+      - name: Check relative Markdown links
+        run: python scripts/check_docs.py
+# ORIGINAL (preserved, not deleted — disabled by comment):
+#       - name: Validate Markdown documents
+#         run: |
+#           python3 - <<'PY'
+#           from pathlib import Path
+#           import sys
+#
+#           files = sorted(Path('.').rglob('*.md'))
+#           if not files:
+#               sys.exit('No Markdown documents found.')
+#           empty = [str(path) for path in files if not path.read_text(encoding='utf-8').strip()]
+#           if empty:
+#               sys.exit('Empty Markdown documents:\n' + '\n'.join(empty))
+#           print(f'Validated {len(files)} non-empty Markdown documents.')
+#           PY

.gitignore

@@ -0,0 +1,36 @@
+# Editor and operating system
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+
+# Local environment and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# JavaScript / TypeScript
+node_modules/
+coverage/
+.vite/
+.turbo/
+
+# Local runtime data
+*.log
+data/

AGENTS.md

@@ -0,0 +1,70 @@
+# OpenCluster agent and contributor instructions
+
+## Mission and current scope
+
+OpenCluster is planned as a self-hosted control plane for cluster nodes, infrastructure, AI agents, and distributed workloads: **One dashboard. Every node. Total control.** The repository is currently in Phase 0. The dashboard, API, node agent, and deployment stack are not implemented. Do not build product features until a maintainer selects an implementation milestone.
+
+## Before changing anything
+
+1. Read this file and the relevant project documentation before editing. Inspect the current code, callers, configuration, and tests; do not rely on prior assumptions.
+2. Check `git status`, the current branch, and recent history. Preserve existing work and commits. Never force-push or overwrite unrelated changes.
+3. Identify every caller, test, fixture, export, and document affected by the change. Make the smallest complete change and report any known limitation.
+4. Do not remove existing behavior without an explicit migration plan. Never commit credentials, tokens, private keys, or production data.
+5. Never delete existing code. When disabling code is required, preserve it as a language comment beginning `ORIGINAL (preserved, not deleted — disabled by comment):`.
+
+## Repository organization
+
+- `frontend/` — planned React and TypeScript dashboard.
+- `backend/` — planned FastAPI control plane.
+- `node-agent/` — planned lightweight Linux node service.
+- `infrastructure/` — deployment and operations assets.
+- `docs/` — product requirements, architecture, protocols, operations, and decisions.
+- `scripts/` — repository maintenance utilities.
+- `tests/` — automated checks; application tests will be added with application code.
+- `.codex/agents/` — project-scoped Codex role definitions.
+
+## Architecture and security rules
+
+- Follow `docs/ARCHITECTURE.md`, `docs/SECURITY_ARCHITECTURE.md`, `docs/API_DESIGN.md`, and `docs/DATABASE_DESIGN.md`. They describe proposals until implementation exists.
+- Keep module boundaries explicit. Frontend code must not access the database directly; the node agent must not trust control-plane input without authentication and authorization.
+- Default to least privilege. Privileged node actions require authenticated identity, authorization, audit records, bounded operations, and explicit confirmation where destructive.
+- Never expose unrestricted remote shells or arbitrary cross-node command execution. Do not add secrets to code, logs, examples, or fixtures.
+- Choose libraries only when they solve an approved need. Record material architecture changes in `docs/DECISIONS.md`.
+
+## Coding conventions
+
+- TypeScript: strict mode, TSX for React components, explicit types at public boundaries, accessible HTML semantics, and minimal handwritten CSS.
+- Python: type public interfaces, validate at trust boundaries, use structured logging, and preserve useful exception context without exposing secrets.
+- Keep formatting and linting tools aligned with checked-in configuration. Use Conventional Commits and semantic versioning after the first release; no release version exists yet.
+- Do not introduce dependencies, configuration, abstractions, or compatibility layers without a current requirement.
+
+## Agent delegation
+
+Use `.codex/agents/` roles for focused work. Delegate only independent tasks with non-overlapping file ownership; communicate scope and shared-work constraints. The reviewer reports findings and does not approve automatically. Automated review cannot be represented as independent human review.
+
+When a task has independent workstreams and the client supports delegation, use separate roles with explicit file ownership and consolidate their results. Do not delegate overlapping edits.
+
+## Code review standards
+
+Reviewers should check correctness, regressions, architecture and interface consistency, security and authorization, performance implications, maintainability, accessibility where relevant, and test coverage. Findings must be evidence-based, actionable, and ordered by severity. Do not approve automatically or treat automated review as independent human approval.
+
+## Tests and validation
+
+- Run focused checks for changed behavior, then relevant broader checks when they exist. Do not claim commands passed unless they were run.
+- During Phase 0, CI validates documentation links and repository configuration only. Application build workflows must wait until application manifests and build tooling exist.
+- Add regression tests for non-trivial behavior, failure paths, and security-sensitive logic. Keep performance benchmarks reproducible and do not invent targets or results.
+
+## Documentation requirements
+
+Update documentation when behavior, interfaces, security assumptions, dependencies, or deployment requirements change. Clearly mark planned and experimental work. Verify commands and internal links; do not document unsupported installation or deployment procedures as ready to use.
+
+## GitHub collaboration
+
+- `imzyrix` is the designated maintainer and implementation account; `aaryaavinash` is the designated collaborator/reviewer. Verify the active account and the actual Git push identity separately.
+- Use separate, accurate Git author identities. Never impersonate a reviewer, manufacture approvals, or bypass branch protections. Both accounts may participate only where GitHub permissions allow.
+- Work on branches and submit pull requests to `main`; request review from an authorized reviewer. Address findings and satisfy required CI and repository protections before merging.
+- See `docs/GITHUB_WORKFLOW.md` for account switching, credential checks, and review procedure.
+
+## Definition of done
+
+A change is done when its scope is complete, relevant checks pass (or limitations are stated), docs are current, no secrets or unrelated edits are present, and it is committed through the authorized branch and review workflow. Do not merge a pull request unless applicable checks and approvals are satisfied.

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+Not released yet. No application version has been published.
+
+Future entries will follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories: Added, Changed, Deprecated, Removed, Fixed, and Security. Versions will follow semantic versioning once releases begin.

CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+## Our commitment
+
+OpenCluster welcomes people with different backgrounds, experience levels, and perspectives. We aim to make participation respectful and constructive for everyone.
+
+## Expected behavior
+
+- Be considerate, patient, and respectful in discussion and review.
+- Assume good intent while addressing the impact of words or actions.
+- Give specific, useful feedback and accept correction gracefully.
+- Respect privacy; do not publish another person's private information without consent.
+- Keep project discussions focused on the work and its users.
+
+## Unacceptable behavior
+
+Harassment, discriminatory language or conduct, personal attacks, intimidation, deliberate disruption, unwanted sexual attention, and sharing private information without consent are not acceptable.
+
+## Enforcement
+
+Project maintainers may remove content, restrict participation, or take other proportionate action in response to conduct that harms the community. Reports should be sent privately to the project maintainers through the contact route listed in the repository's GitHub organization or repository settings. Do not use public issues for sensitive reports. Maintainers should handle reports confidentially and fairly, and should not act as the sole decision-maker when they are directly involved in a report.
+
+This policy applies in project spaces and when someone is publicly representing OpenCluster. It is intended to guide community participation and does not replace applicable law or platform policies.