Skip to content

Commit a1d63c4

Browse files
Lightheartdevsclaude
authored and
User Name
committed
Restructure README, add CI workflows, issue templates, and v1.0.0 release notes
- Rewrite root README: architecture diagram (Mermaid), "Who Is This For" section (3 audiences), restructured flow for first-impression conversion - Add CI: ShellCheck for bash, Ruff for Python, docker compose validation - Add GitHub issue templates (bug report, feature request) with YAML forms - Add CONTRIBUTING.md with contributor on-ramp - Draft RELEASE-v1.0.0.md with full component table and version numbers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ec0ef0a commit a1d63c4

9 files changed

Lines changed: 597 additions & 51 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: Bug Report
2+
description: Report a bug in Lighthouse AI (Dream Server, Guardian, Memory Shepherd, Token Spy)
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for taking the time to report a bug. Please fill out the sections below so we can reproduce and fix the issue.
9+
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Description
14+
description: A clear summary of the bug.
15+
placeholder: What went wrong?
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: steps-to-reproduce
21+
attributes:
22+
label: Steps to Reproduce
23+
description: Step-by-step instructions to trigger the bug.
24+
placeholder: |
25+
1. Run `./install.sh`
26+
2. Select option X
27+
3. ...
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: expected-behavior
33+
attributes:
34+
label: Expected Behavior
35+
description: What you expected to happen.
36+
validations:
37+
required: true
38+
39+
- type: textarea
40+
id: actual-behavior
41+
attributes:
42+
label: Actual Behavior
43+
description: What actually happened instead.
44+
validations:
45+
required: true
46+
47+
- type: input
48+
id: os
49+
attributes:
50+
label: Operating System
51+
placeholder: "e.g. Ubuntu 24.04, Windows 11, macOS 14"
52+
validations:
53+
required: true
54+
55+
- type: input
56+
id: gpu
57+
attributes:
58+
label: GPU
59+
placeholder: "e.g. NVIDIA RTX 4090 24 GB, AMD RX 7900 XTX, None (CPU only)"
60+
validations:
61+
required: true
62+
63+
- type: input
64+
id: docker-version
65+
attributes:
66+
label: Docker Version
67+
placeholder: "e.g. Docker 27.1.1, Podman 5.0"
68+
validations:
69+
required: true
70+
71+
- type: input
72+
id: vram
73+
attributes:
74+
label: VRAM
75+
placeholder: "e.g. 24 GB, 8 GB"
76+
validations:
77+
required: true
78+
79+
- type: textarea
80+
id: logs
81+
attributes:
82+
label: Logs
83+
description: Paste any relevant log output. This will be rendered as code.
84+
render: shell
85+
validations:
86+
required: false
87+
88+
- type: textarea
89+
id: screenshots
90+
attributes:
91+
label: Screenshots
92+
description: If applicable, add screenshots to help illustrate the problem.
93+
validations:
94+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: "Question / Help"
4+
url: "https://github.com/Light-Heart-Labs/Lighthouse-AI/discussions"
5+
about: "Ask questions and get help from the community"

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement for Lighthouse AI
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Have an idea that would make Lighthouse AI better? We'd love to hear it.
9+
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Description
14+
description: A clear description of the feature you'd like.
15+
placeholder: What should Lighthouse AI do?
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: use-case
21+
attributes:
22+
label: Use Case
23+
description: Why do you need this? What problem does it solve for you?
24+
placeholder: I want this because...
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: proposed-solution
30+
attributes:
31+
label: Proposed Solution
32+
description: If you have an idea for how this could work, describe it here.
33+
validations:
34+
required: false
35+
36+
- type: textarea
37+
id: alternatives-considered
38+
attributes:
39+
label: Alternatives Considered
40+
description: Have you considered other approaches or workarounds?
41+
validations:
42+
required: false

‎.github/workflows/lint-python.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Python Lint
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
ruff:
14+
name: Lint Python with Ruff
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.12"
23+
24+
- name: Install Ruff
25+
run: pip install ruff
26+
27+
- name: Run Ruff on dream-server Python files
28+
run: |
29+
ruff check dream-server/ \
30+
--select E,F,W \
31+
--ignore E501

‎.github/workflows/lint-shell.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: ShellCheck
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
shellcheck:
14+
name: Lint shell scripts
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Install ShellCheck
20+
run: |
21+
sudo apt-get update
22+
sudo apt-get install -y shellcheck
23+
shellcheck --version
24+
25+
- name: Run ShellCheck on dream-server shell scripts
26+
run: |
27+
# Find all .sh files under dream-server/
28+
shfiles=$(find dream-server/ -name '*.sh' -type f)
29+
30+
if [ -z "$shfiles" ]; then
31+
echo "No .sh files found under dream-server/"
32+
exit 0
33+
fi
34+
35+
echo "Found $(echo "$shfiles" | wc -l) shell scripts"
36+
echo ""
37+
38+
# Run shellcheck:
39+
# -e SC1091 exclude "can't follow sourced files"
40+
# -e SC2034 exclude "unused variables" (many are used by sourced files)
41+
# -S warning treat warnings and above as reportable
42+
# shellcheck returns:
43+
# 0 = no issues
44+
# 1 = errors or warnings found
45+
# We fail the job only on error-severity issues by using -S error,
46+
# but still display warnings for visibility.
47+
48+
# First pass: display all warnings and errors for visibility
49+
echo "=== ShellCheck results (warnings + errors) ==="
50+
echo "$shfiles" | xargs shellcheck \
51+
--exclude=SC1091,SC2034 \
52+
--severity=warning \
53+
--format=gcc \
54+
|| true
55+
56+
echo ""
57+
echo "=== Checking for error-severity issues (will fail if found) ==="
58+
59+
# Second pass: fail only on error severity
60+
echo "$shfiles" | xargs shellcheck \
61+
--exclude=SC1091,SC2034 \
62+
--severity=error

‎.github/workflows/validate-compose.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Validate Docker Compose
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "dream-server/docker-compose*.yml"
8+
- "dream-server/compose/**"
9+
pull_request:
10+
branches: [main]
11+
paths:
12+
- "dream-server/docker-compose*.yml"
13+
- "dream-server/compose/**"
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
validate-compose:
20+
name: Validate Docker Compose files
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- name: Validate main docker-compose.yml
26+
run: |
27+
echo "Validating dream-server/docker-compose.yml"
28+
docker compose -f dream-server/docker-compose.yml config --quiet
29+
30+
- name: Validate compose files in dream-server/compose/
31+
run: |
32+
compose_files=$(find dream-server/compose/ -name '*.yml' -type f 2>/dev/null || true)
33+
34+
if [ -z "$compose_files" ]; then
35+
echo "No compose files found in dream-server/compose/"
36+
exit 0
37+
fi
38+
39+
echo "Found compose files:"
40+
echo "$compose_files"
41+
echo ""
42+
43+
failed=0
44+
for f in $compose_files; do
45+
echo "Validating $f ..."
46+
if docker compose -f "$f" config --quiet 2>&1; then
47+
echo " OK"
48+
else
49+
echo " FAILED"
50+
failed=1
51+
fi
52+
done
53+
54+
if [ "$failed" -ne 0 ]; then
55+
echo ""
56+
echo "One or more compose files failed validation."
57+
exit 1
58+
fi
59+
60+
echo ""
61+
echo "All compose files validated successfully."

‎CONTRIBUTING.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Contributing to Lighthouse AI
2+
3+
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.
4+
5+
## Quick Start
6+
7+
1. **Fork** this repository and **clone** your fork locally.
8+
2. Create a **branch** for your work:
9+
```bash
10+
git checkout -b my-change
11+
```
12+
3. Make your changes, test them locally, and commit.
13+
4. Open a **pull request** against `main`.
14+
15+
That's it. No CLA, no hoops.
16+
17+
## What We're Looking For
18+
19+
All kinds of contributions are valuable. Here are some great places to start:
20+
21+
- **Bug fixes** -- something broken? Fix it and send a PR.
22+
- **Documentation improvements** -- clearer install instructions, better troubleshooting guides, typo fixes.
23+
- **New cookbook recipes** -- workflows, prompt templates, or integration examples that help other users.
24+
- **Test coverage** -- more tests means fewer surprises.
25+
- **Feature work** -- check the issue tracker for ideas, or propose your own.
26+
27+
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.
28+
29+
## Code Style
30+
31+
Nothing exotic:
32+
33+
- **Shell scripts** are written in Bash. Use `shellcheck` if you can.
34+
- **Python** uses standard formatting (we're not picky -- just be consistent with the file you're editing).
35+
- Keep things readable. Comments are welcome where intent isn't obvious.
36+
37+
## Pull Request Process
38+
39+
1. **Describe your changes** in the PR description. A sentence or two is fine for small changes; more detail helps for larger ones.
40+
2. **Link related issues** if they exist (e.g. "Fixes #42").
41+
3. Make sure existing functionality isn't broken.
42+
4. A maintainer will review your PR and may suggest changes. We try to be responsive.
43+
44+
## Where to Ask Questions
45+
46+
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.
47+
48+
## License
49+
50+
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.
51+
52+
---
53+
54+
Thanks for helping make local AI infrastructure better for everyone.

0 commit comments

Comments
 (0)