Restructure README, add CI workflows, issue templates, and v1.0.0 rel…

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,94 @@
+name: Bug Report
+description: Report a bug in Lighthouse AI (Dream Server, Guardian, Memory Shepherd, Token Spy)
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks 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 summary of the bug.
+      placeholder: What went wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Step-by-step instructions to trigger the bug.
+      placeholder: |
+        1. Run `./install.sh`
+        2. Select option X
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happened instead.
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "e.g. Ubuntu 24.04, Windows 11, macOS 14"
+    validations:
+      required: true
+
+  - type: input
+    id: gpu
+    attributes:
+      label: GPU
+      placeholder: "e.g. NVIDIA RTX 4090 24 GB, AMD RX 7900 XTX, None (CPU only)"
+    validations:
+      required: true
+
+  - type: input
+    id: docker-version
+    attributes:
+      label: Docker Version
+      placeholder: "e.g. Docker 27.1.1, Podman 5.0"
+    validations:
+      required: true
+
+  - type: input
+    id: vram
+    attributes:
+      label: VRAM
+      placeholder: "e.g. 24 GB, 8 GB"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Paste any relevant log output. This will be rendered as code.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help illustrate the problem.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: "Question / Help"
+    url: "https://github.com/Light-Heart-Labs/Lighthouse-AI/discussions"
+    about: "Ask questions and get help from the community"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature Request
+description: Suggest a new feature or improvement for Lighthouse AI
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea that would make Lighthouse AI better? We'd love to hear it.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the feature you'd like.
+      placeholder: What should Lighthouse AI do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Why do you need this? What problem does it solve for you?
+      placeholder: I want this because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: If you have an idea for how this could work, describe it here.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives-considered
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered other approaches or workarounds?
+    validations:
+      required: false

.github/workflows/lint-python.yml

@@ -0,0 +1,31 @@
+name: Python Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    name: Lint Python with Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Ruff
+        run: pip install ruff
+
+      - name: Run Ruff on dream-server Python files
+        run: |
+          ruff check dream-server/ \
+            --select E,F,W \
+            --ignore E501

.github/workflows/lint-shell.yml

@@ -0,0 +1,62 @@
+name: ShellCheck
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  shellcheck:
+    name: Lint shell scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+          shellcheck --version
+
+      - name: Run ShellCheck on dream-server shell scripts
+        run: |
+          # Find all .sh files under dream-server/
+          shfiles=$(find dream-server/ -name '*.sh' -type f)
+
+          if [ -z "$shfiles" ]; then
+            echo "No .sh files found under dream-server/"
+            exit 0
+          fi
+
+          echo "Found $(echo "$shfiles" | wc -l) shell scripts"
+          echo ""
+
+          # Run shellcheck:
+          #   -e SC1091  exclude "can't follow sourced files"
+          #   -e SC2034  exclude "unused variables" (many are used by sourced files)
+          #   -S warning treat warnings and above as reportable
+          # shellcheck returns:
+          #   0 = no issues
+          #   1 = errors or warnings found
+          # We fail the job only on error-severity issues by using -S error,
+          # but still display warnings for visibility.
+
+          # First pass: display all warnings and errors for visibility
+          echo "=== ShellCheck results (warnings + errors) ==="
+          echo "$shfiles" | xargs shellcheck \
+            --exclude=SC1091,SC2034 \
+            --severity=warning \
+            --format=gcc \
+            || true
+
+          echo ""
+          echo "=== Checking for error-severity issues (will fail if found) ==="
+
+          # Second pass: fail only on error severity
+          echo "$shfiles" | xargs shellcheck \
+            --exclude=SC1091,SC2034 \
+            --severity=error

.github/workflows/validate-compose.yml

@@ -0,0 +1,61 @@
+name: Validate Docker Compose
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "dream-server/docker-compose*.yml"
+      - "dream-server/compose/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "dream-server/docker-compose*.yml"
+      - "dream-server/compose/**"
+
+permissions:
+  contents: read
+
+jobs:
+  validate-compose:
+    name: Validate Docker Compose files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate main docker-compose.yml
+        run: |
+          echo "Validating dream-server/docker-compose.yml"
+          docker compose -f dream-server/docker-compose.yml config --quiet
+
+      - name: Validate compose files in dream-server/compose/
+        run: |
+          compose_files=$(find dream-server/compose/ -name '*.yml' -type f 2>/dev/null || true)
+
+          if [ -z "$compose_files" ]; then
+            echo "No compose files found in dream-server/compose/"
+            exit 0
+          fi
+
+          echo "Found compose files:"
+          echo "$compose_files"
+          echo ""
+
+          failed=0
+          for f in $compose_files; do
+            echo "Validating $f ..."
+            if docker compose -f "$f" config --quiet 2>&1; then
+              echo "  OK"
+            else
+              echo "  FAILED"
+              failed=1
+            fi
+          done
+
+          if [ "$failed" -ne 0 ]; then
+            echo ""
+            echo "One or more compose files failed validation."
+            exit 1
+          fi
+
+          echo ""
+          echo "All compose files validated successfully."

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Lighthouse AI
+
+First off, thanks for wanting to contribute! Lighthouse AI is an open source project and we welcome help from everyone -- whether you're fixing a typo, adding a cookbook recipe, or tackling a full feature.
+
+## Quick Start
+
+1. **Fork** this repository and **clone** your fork locally.
+2. Create a **branch** for your work:
+   ```bash
+   git checkout -b my-change
+   ```
+3. Make your changes, test them locally, and commit.
+4. Open a **pull request** against `main`.
+
+That's it. No CLA, no hoops.
+
+## What We're Looking For
+
+All kinds of contributions are valuable. Here are some great places to start:
+
+- **Bug fixes** -- something broken? Fix it and send a PR.
+- **Documentation improvements** -- clearer install instructions, better troubleshooting guides, typo fixes.
+- **New cookbook recipes** -- workflows, prompt templates, or integration examples that help other users.
+- **Test coverage** -- more tests means fewer surprises.
+- **Feature work** -- check the issue tracker for ideas, or propose your own.
+
+If you're new here, look for issues labeled **`good first issue`**. These are scoped, well-defined tasks that are a great way to get familiar with the codebase.
+
+## Code Style
+
+Nothing exotic:
+
+- **Shell scripts** are written in Bash. Use `shellcheck` if you can.
+- **Python** uses standard formatting (we're not picky -- just be consistent with the file you're editing).
+- Keep things readable. Comments are welcome where intent isn't obvious.
+
+## Pull Request Process
+
+1. **Describe your changes** in the PR description. A sentence or two is fine for small changes; more detail helps for larger ones.
+2. **Link related issues** if they exist (e.g. "Fixes #42").
+3. Make sure existing functionality isn't broken.
+4. A maintainer will review your PR and may suggest changes. We try to be responsive.
+
+## Where to Ask Questions
+
+Not sure about something? Open a thread in [GitHub Discussions](https://github.com/Light-Heart-Labs/Lighthouse-AI/discussions). We're happy to help you figure out the best approach before you write any code.
+
+## License
+
+By contributing to Lighthouse AI, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE), the same license that covers this project.
+
+---
+
+Thanks for helping make local AI infrastructure better for everyone.