[codex] bootstrap repository scaffolding

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,41 @@
+name: Bug
+description: Report a defect in docs, protocol design, services, apps, hardware, crypto, or infra.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What is broken or incorrect?
+    validations:
+      required: true
+  - type: textarea
+    id: current
+    attributes:
+      label: Current Behavior
+      description: What happens now?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should happen instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction Or Evidence
+      description: Steps, logs, screenshots, file references, or reasoning.
+    validations:
+      required: false
+  - type: textarea
+    id: scope
+    attributes:
+      label: Suspected Scope
+      description: Which area or directory is likely affected?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,38 @@
+name: Feature
+description: Propose a FlowMemory product, protocol, service, app, or infra feature.
+title: "[Feature]: "
+labels:
+  - feature
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for scoped implementation proposals. Keep heavy data, secrets, and private credentials out of issues.
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should exist after this feature is complete?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: Which directories, systems, or interfaces are in scope?
+    validations:
+      required: true
+  - type: textarea
+    id: boundaries
+    attributes:
+      label: Boundaries
+      description: What is explicitly out of scope?
+    validations:
+      required: true
+  - type: textarea
+    id: tests
+    attributes:
+      label: Tests Or Verification
+      description: What checks should prove this works?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/hardware.yml

@@ -0,0 +1,38 @@
+name: Hardware
+description: Track FlowRouter, Meshtastic, LoRa, enclosure, or field-test work.
+title: "[Hardware]: "
+labels:
+  - hardware
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Meshtastic and LoRa are low-bandwidth control signaling paths. Do not assume normal internet bandwidth.
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What hardware outcome is needed?
+    validations:
+      required: true
+  - type: textarea
+    id: components
+    attributes:
+      label: Components
+      description: Devices, radios, sensors, enclosure parts, boards, or power systems involved.
+    validations:
+      required: false
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints
+      description: Bandwidth, power, size, thermal, safety, field, or manufacturing constraints.
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation
+      description: How should this be tested or field-validated?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/research.yml

@@ -0,0 +1,38 @@
+name: Research
+description: Track AI memory, neural geometry, protocol, reliability, or appchain/L1 research.
+title: "[Research]: "
+labels:
+  - research
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for research questions, hypotheses, experiments, and literature notes.
+  - type: textarea
+    id: question
+    attributes:
+      label: Research Question
+      description: What are we trying to learn?
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What project context or prior work matters?
+    validations:
+      required: true
+  - type: textarea
+    id: method
+    attributes:
+      label: Proposed Method
+      description: How should the research be conducted?
+    validations:
+      required: false
+  - type: textarea
+    id: output
+    attributes:
+      label: Expected Output
+      description: Paper note, decision record, experiment result, prototype, or other artifact.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/security.yml

@@ -0,0 +1,46 @@
+name: Security
+description: Report or track protocol, service, hardware, crypto, or operational security work.
+title: "[Security]: "
+labels:
+  - security
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not include live secrets, private keys, seed phrases, or exploitable private details in public issue text.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Protocol
+        - Contracts
+        - Indexer or verifier
+        - AI memory
+        - Hardware
+        - Infrastructure
+        - Supply chain
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: concern
+    attributes:
+      label: Concern
+      description: What is the security concern?
+    validations:
+      required: true
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact
+      description: What could go wrong if this is real?
+    validations:
+      required: true
+  - type: textarea
+    id: recommendation
+    attributes:
+      label: Recommendation
+      description: Proposed fix, mitigation, or next investigation step.
+    validations:
+      required: false

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+# Summary
+
+## What Changed
+
+- TBD
+
+## Why
+
+- TBD
+
+## Tests Or Checks
+
+- [ ] I ran the relevant tests or checks.
+- [ ] No tests exist yet for this scope.
+
+## Scope Discipline
+
+- [ ] I read `AGENTS.md`.
+- [ ] I read `docs/START_HERE.md`.
+- [ ] I read `docs/FLOWMEMORY_HQ_CONTEXT.md`.
+- [ ] I read `docs/CURRENT_STATE.md`.
+- [ ] I only edited files in my assigned scope.
+- [ ] I did not hardcode secrets.
+
+## Risk And Follow-Ups
+
+- TBD

.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  repository-hygiene:
+    name: Repository hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check required bootstrap paths
+        shell: bash
+        run: |
+          required_paths=(
+            "AGENTS.md"
+            "README.md"
+            "docs/FLOWMEMORY_HQ_CONTEXT.md"
+            "docs/START_HERE.md"
+            "docs/PROJECT_CHARTER.md"
+            "docs/CURRENT_STATE.md"
+            "docs/ROADMAP.md"
+            "docs/ARCHITECTURE.md"
+            "docs/SECURITY_MODEL.md"
+            "docs/AGENT_ROLES.md"
+            "docs/DECISIONS"
+            "contracts"
+            "services"
+            "apps"
+            "hardware"
+            "research"
+            "crypto"
+            "infra/scripts"
+            "inbox/claude-code"
+            "inbox/old-prompts"
+            "inbox/unsorted"
+            ".github/pull_request_template.md"
+            ".github/ISSUE_TEMPLATE/feature.yml"
+            ".github/ISSUE_TEMPLATE/research.yml"
+            ".github/ISSUE_TEMPLATE/hardware.yml"
+            ".github/ISSUE_TEMPLATE/security.yml"
+            ".github/ISSUE_TEMPLATE/bug.yml"
+          )
+
+          missing=0
+          for path in "${required_paths[@]}"; do
+            if [[ ! -e "$path" ]]; then
+              echo "::error::Missing required path: $path"
+              missing=1
+            fi
+          done
+
+          exit "$missing"
+
+      - name: Check for obvious committed secrets
+        shell: bash
+        run: |
+          patterns=(
+            'BEGIN (RSA|OPENSSH|PRIVATE) K[E]Y'
+            'AWS_SECRET_ACCESS_K[E]Y'
+            'PRIVATE_K[E]Y='
+            'SECRET_K[E]Y='
+            'gho_[A-Za-z0-9_]+'
+          )
+
+          for pattern in "${patterns[@]}"; do
+            if grep -RInE "$pattern" . --exclude-dir=.git; then
+              echo "::error::Potential secret detected. Remove it or document why this is a false positive."
+              exit 1
+            fi
+          done

AGENTS.md

@@ -0,0 +1,42 @@
+# FlowMemory Agent Instructions
+
+These instructions apply to every agent, assistant, script, and human operating in this repository.
+
+## Source Of Truth
+
+- Treat GitHub as the source of truth for project state, issues, pull requests, reviews, and final history.
+- Read `docs/START_HERE.md` before starting any task.
+- Read `docs/FLOWMEMORY_HQ_CONTEXT.md` before making design or implementation choices.
+- Read `docs/CURRENT_STATE.md` immediately before working so you understand what exists and what does not.
+- If local context conflicts with GitHub, stop and reconcile the difference before editing.
+
+## Scope Discipline
+
+- Work only on the assigned scope.
+- Do not edit unrelated files.
+- Do not rename, move, or delete files outside the task unless the task explicitly asks for it.
+- Do not build product features during bootstrap, planning, or research tasks.
+- When blocked, document the blocker and the smallest useful next step.
+
+## Engineering Rules
+
+- Do not hardcode secrets, tokens, private keys, seed phrases, RPC credentials, API keys, or webhook URLs.
+- Keep heavy AI, model, memory, artifact, and media data off-chain.
+- Remember that storage is not free and transaction hashes do not store arbitrary data.
+- Remember that Uniswap v4 hooks cannot know `txHash` or `logIndex` at execution time.
+- Let indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs.
+- Store roots, receipts, commitments, attestations, proofs, and work state on-chain only when they are intentionally part of the protocol.
+- Treat Meshtastic and LoRa as low-bandwidth control signaling, not normal internet bandwidth.
+- Add tests where practical, especially for protocol logic, parsers, cryptography, indexers, verifiers, and hardware control paths.
+
+## Collaboration
+
+- Prefer small, reviewable pull requests.
+- Keep documentation updated when changing architecture, security assumptions, public contracts, or agent workflows.
+- Record durable architectural decisions in `docs/DECISIONS/`.
+- Use issues for unknowns, research tasks, hardware tasks, security tasks, bugs, and feature proposals.
+- End every task with a PR-ready summary that includes:
+  - What changed
+  - Why it changed
+  - Tests or checks run
+  - Risks, assumptions, and follow-ups