diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..16f95ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,18 @@ +--- +name: Bug report +about: A documented flag, fix, or setup step doesn't actually work as described +title: "" +labels: bug +--- + +**What's documented, and where** (file + section/link): + +**What you did**: + +**What you expected** (per the docs): + +**What actually happened**: + +**Environment** — OS, `llama.cpp` build/commit, Open WebUI version, GPU: see [docs/compatibility.md](../../docs/compatibility.md) for what's already tested. If yours differs, say so explicitly: + +**How you confirmed it's a real issue** (a command you ran, a log line, not just "seems off") — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for why this matters: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b60b613 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: https://github.com/onkarbadve/localai/security/policy + about: Please report security issues privately per SECURITY.md, not as a public issue. diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..2b37b08 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,12 @@ +--- +name: Documentation improvement +about: A broken link, unclear explanation, or formatting issue in the docs +title: "" +labels: documentation +--- + +**File(s) affected**: + +**What's wrong or unclear**: + +**Suggested fix** (if you have one): diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..3cc8633 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,14 @@ +--- +name: Feature request +about: Suggest something for this setup — please read the scope note below first +title: "" +labels: enhancement +--- + +Per [CONTRIBUTING.md](../../CONTRIBUTING.md#whats-out-of-scope), this repo documents one person's actual hardware and choices, not a general-purpose product — feature requests for the setup itself are generally out of scope. This template is for the rare case that's still worth raising: e.g. a documented rough edge that has a concrete, verifiable fix, or a compatibility gap you've hit yourself. + +**What you're running into**: + +**What you'd want instead**: + +**Have you verified this against your own setup** (not just a hypothetical)? diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml new file mode 100644 index 0000000..2faa5fe --- /dev/null +++ b/.github/workflows/docs-lint.yml @@ -0,0 +1,40 @@ +name: Docs Lint + +# Documentation-only CI: this repo has no build or test suite (it's +# infrastructure/config, not a library — see AGENTS.md), so this workflow +# only validates markdown formatting and links. No build steps, no tests. +on: + push: + branches: [main] + paths: ["**/*.md"] + pull_request: + paths: ["**/*.md"] + workflow_dispatch: + +permissions: + contents: read + +jobs: + markdownlint: + name: Markdown formatting + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: | + **/*.md + !llama.cpp/** + + link-check: + name: Markdown links + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: lycheeverse/lychee-action@v2 + with: + args: >- + --config lychee.toml + --no-progress + "**/*.md" + fail: true diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 0000000..1d9535f --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,15 @@ +{ + // This repo writes prose as one paragraph per line (no hard-wrapping) and + // uses a couple of intentional structural choices (centered README header, + // compact tables) that trip the stricter default rules below without being + // actual problems. Disabled here rather than reformatting working content. + "default": true, + "MD013": false, // line-length — prose isn't hard-wrapped in this repo + "MD033": false, // no-inline-html — README's centered
header + "MD041": false, // first-line-heading — README's
precedes the H1 + "MD022": false, // blanks-around-headings — pre-existing SETUP.md style + "MD032": false, // blanks-around-lists — pre-existing SETUP.md style + "MD024": false, // no-duplicate-heading — every docs/ file repeats "Related documents" + "MD060": false, // table-column-style — not yet applied repo-wide + "MD018": false // no-missing-space-atx — linkedin-post.md's real hashtags, not headings +} diff --git a/CHANGELOG.md b/CHANGELOG.md index f8caa38..1497642 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ Version history of this repository and the setup it documents. This is a summary view — [JOURNAL.md](JOURNAL.md) is the detailed, dated source of truth; [adr/](adr/) explains the reasoning behind the decisions that stuck. Entries are grouped into rough milestones, not formal semver releases (there's no package here to version) — the numbers exist to give a sense of order and progress. +## v1.5 — Repository polish and CI (2026-07-31) + +- README: tightened "Features" into "Key Takeaways" and "Repository Structure" into "Repository at a Glance" (added a quick-facts table) for first-screen scannability. +- Added `docs/compatibility.md` (tested OS/tool versions) and `docs/github-setup.md` (manual GitHub configuration checklist). +- Added a static PNG export of the architecture diagram (`docs/images/architecture.png`) alongside the existing Mermaid source. +- Added `.github/workflows/docs-lint.yml` — markdown formatting and link checks, no build/test steps — plus minimal issue templates (`.github/ISSUE_TEMPLATE/`). +- Terminology and cross-link consistency pass across every markdown file; no functional or technical content changed. + ## v1.4 — Documentation overhaul (2026-07-30 onward) - Restructured `README.md` around overview / features / architecture / quick start / repo structure / screenshots / benchmarks / documentation / roadmap. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c17019..f0eca11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,8 @@ This repository is primarily a personal engineering notebook — a running recor Read [AGENTS.md](AGENTS.md) before proposing documentation changes — it covers this repo's specific conventions (comment style in scripts, when to update `JOURNAL.md` vs. `docs/`, why content gets moved rather than deleted). +Maintainer-only GitHub configuration (repo description, topics, release strategy) is checklisted separately in [docs/github-setup.md](docs/github-setup.md) — it doesn't affect contributions, just repo settings. + ## Code of conduct Be respectful and constructive. This is a small, personal project maintained by one person in their spare time — response times may be slow. diff --git a/JOURNAL.md b/JOURNAL.md index add2775..12b814b 100644 --- a/JOURNAL.md +++ b/JOURNAL.md @@ -17,6 +17,31 @@ Older entries below predate this template and stay in their original free-form n --- +## 2026-07-31 — Final repository polish: discoverability, consistency, and CI + +**Goal**: a documentation-only polish pass — improve first-time-visitor experience, terminology consistency, and navigation across the already-complete doc set, without adding new documentation or rewriting working content. + +**Changes**: +- README: retitled "Features" → "Key Takeaways" (same evidence-backed bullets, cross-linked to the docs that back each claim) and "Repository Structure" → "Repository at a Glance" (added a compact quick-facts table above the existing directory tree). +- Fixed two Iris Xe wording inconsistencies (`adr/0004-vulkan-backend.md`, `docs/hardware.md`) to match the "Intel Iris Xe iGPU" phrasing used everywhere else. +- Exported the `docs/architecture.md` Mermaid diagram to a static PNG (`docs/images/architecture.png`, via `mmdc`) and referenced both versions in that doc, for viewers without Mermaid rendering. +- Added `docs/github-setup.md` — a reusable checklist for the GitHub-UI-only configuration (description, topics, social preview, homepage, release strategy, branch protection, discussions) that doesn't live in files. +- Added `docs/compatibility.md` — a tested-versions matrix for Fedora/Windows/Podman/Open WebUI/`llama.cpp`/Vulkan/Intel graphics drivers, with `TODO`s left wherever a version genuinely isn't recorded anywhere else in the repo, per the no-fabrication rule in `AGENTS.md`. +- Added `.github/workflows/docs-lint.yml` (markdownlint-cli2 + lychee link check, docs-only, no build/test steps), `.markdownlint.jsonc`, and `lychee.toml`. +- Added minimal issue templates (`.github/ISSUE_TEMPLATE/`: bug report, documentation, feature request + config.yml), the feature-request one explicitly pointing at `CONTRIBUTING.md`'s out-of-scope note given this repo documents one person's setup, not a product. +- Fixed small pre-existing markdown lint findings surfaced while configuring the lint job: a missing blank line around a fenced code block (`docs/troubleshooting.md`), and three bare URLs/email/unit-name false-positives wrapped correctly (`SECURITY.md`, `SETUP.md`, `linkedin-post.md`). +- Cross-linked the two new docs into README's Documentation table, `docs/hardware.md`, `docs/troubleshooting.md`, and `CONTRIBUTING.md`'s "Related documents"/workflow sections. + +**Results**: `npx markdownlint-cli2 "**/*.md"` and a custom internal-link checker both run clean (the only "broken" links are the two pre-existing, expected ones into the gitignored `llama.cpp/` checkout — see `docs/hardware.md#why-models-and-llamacpp-arent-in-git`). `codespell` found nothing beyond one confirmed false positive (``, a literal template tag). README grew from 167 to 179 lines — within the "don't significantly increase length" constraint for this task. + +**Problems**: none blocking. The task brief referenced README sections ("Key Takeaways", "Repository at a Glance") that didn't exist under those exact names yet — treated as a rename/tighten of the closest existing sections ("Features", "Repository Structure") rather than new, separately-maintained content, to avoid duplication. + +**Lessons**: this repo's existing documentation was already unusually consistent (single terminology convention, dense cross-linking, no fabricated numbers) — most of the "audit" phases of this task confirmed a clean bill of health rather than finding real problems, which is itself worth recording so a future pass doesn't re-litigate the same ground. + +**Next steps**: none opened by this pass. `docs/compatibility.md`'s `TODO` rows (Windows edition/build, Podman version, `llama.cpp`/Vulkan/Mesa versions on Fedora) are real gaps — worth filling in next time any of those get touched for an unrelated reason, not urgent enough to chase down standalone. + +--- + ## 2026-07-30 — Documented the Podman-over-Docker rationale (retroactively, no re-litigation) User asked why Podman was chosen for Open WebUI/Open Terminal over Docker; no prior journal entry recorded an explicit decision, so it was never actually debated in-session - Podman was simply the starting choice both container scripts were built on (`start-open-webui.sh`, `start-open-terminal.sh`, see SETUP.md). Capturing the reasoning now so it isn't lost: diff --git a/README.md b/README.md index f9bd5c9..d7d6769 100644 --- a/README.md +++ b/README.md @@ -39,14 +39,14 @@ This repo is both a working setup and its own documentation: every bug, workarou - Enterprise AI infrastructure or multi-tenant deployment - Distributed/clustered serving across multiple machines -## Features +## Key Takeaways - **Zero cloud dependency** — every model runs locally on integrated graphics, nothing leaves the machine. -- **Vulkan iGPU offload** — full-layer GPU offload on an Intel Iris Xe iGPU, no discrete card required. +- **Vulkan iGPU offload** — full-layer GPU offload on an Intel Iris Xe iGPU, no discrete card required, sustaining ~9–9.8 tok/s (full numbers in [`docs/benchmarks.md`](docs/benchmarks.md)). - **Dual-model chat** — a production agent-mode model and a separate blunt/uncensored model, both registered in Open WebUI, run mutually exclusively without reconfiguration. -- **Agent tooling** — real tool-calling (Builtin Tools) and a shell/file Integration (Open Terminal), verified end-to-end through Open WebUI, not just curl. +- **Agent tooling** — real tool-calling (Builtin Tools) and a shell/file Integration (Open Terminal), verified end-to-end through Open WebUI in 9/9 real tests, not just curl. - **Remote access** — reachable from a phone over a Tailscale VPN overlay, no port-forwarding or public exposure. -- **Documented crash hardening** — local patches and mitigations for a real iGPU fence-timeout bug, turning silent crashes into clean, recoverable errors. +- **Documented crash hardening** — local patches and mitigations for a real iGPU fence-timeout bug, turning silent crashes into clean, recoverable errors (see [`docs/troubleshooting.md`](docs/troubleshooting.md)). ## Architecture @@ -81,7 +81,17 @@ This is the simplified shape of it. For the full diagram — both `llama-server` Models aren't checked into this repo (multi-GB GGUF files). Building `llama.cpp` from source, placing model weights, Tailscale setup, and every flag's reasoning are in [`SETUP.md`](SETUP.md) — start there for anything beyond running an already-built setup. -## Repository Structure +## Repository at a Glance + +| | | +|---|---| +| **Hardware** | Intel i5-12500H · Intel Iris Xe iGPU · 16GB RAM — no discrete GPU | +| **OS** | Fedora 44 (daily driver) · Windows (origin, preserved) | +| **Inference** | `llama.cpp`, Vulkan backend, full-layer GPU offload | +| **Chat frontend** | Open WebUI + Open Terminal, rootless Podman | +| **Remote access** | Tailscale VPN overlay | +| **License** | MIT | +| **Status** | Active daily driver ([`JOURNAL.md`](JOURNAL.md)) | ```text LocalAI/ @@ -137,6 +147,8 @@ Full numbers, multi-turn cache-reuse data, and agent-mode round-trip timings: [` | [`docs/troubleshooting.md`](docs/troubleshooting.md) | Structured Problem/Cause/Solution/Verification writeups | | [`docs/lessons-learned.md`](docs/lessons-learned.md) | Practical conclusions from real experimentation, by topic | | [`docs/roadmap.md`](docs/roadmap.md) | Completed / upcoming / future-idea work, in more detail than below | +| [`docs/compatibility.md`](docs/compatibility.md) | Tested versions of every OS/tool in the stack | +| [`docs/github-setup.md`](docs/github-setup.md) | Manual GitHub configuration checklist (topics, social preview, releases) | | [`adr/`](adr/) | Architecture Decision Records — why the stable, load-bearing choices were made | | [`JOURNAL.md`](JOURNAL.md) | Dated running log — newest entries first, the historical source of truth | | [`CHANGELOG.md`](CHANGELOG.md) | Version history of this repository itself | diff --git a/SECURITY.md b/SECURITY.md index daede26..d63ccac 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,7 +13,7 @@ Relevant components, for context on what a report might touch: If you find a real security issue in **this repository's own scripts or documented configuration** (for example: a script that would expose a service more broadly than documented, an API key handled unsafely, or a documented mitigation that's actually ineffective), please report it privately rather than opening a public issue: -**onkarbadve@gmail.com** +**** Include: - What you found and why it's a security issue (not just a bug). diff --git a/SETUP.md b/SETUP.md index 16f4d4c..2ec80a0 100644 --- a/SETUP.md +++ b/SETUP.md @@ -123,7 +123,7 @@ Rootless Podman container (`ghcr.io/open-webui/open-webui:main`), point at which - Data persisted in a named Podman volume (`open-webui-data`), not bind-mounted. - Script is idempotent: first run creates the container, later runs just `podman start` the existing one. -UI: http://localhost:3000 — first visit creates the local admin account. Switching which llama.cpp model is active just means restarting the underlying `start-*.sh` script for the port you want live; Open WebUI already has both 8080 and 8081 registered as connections (see above), so it reconnects automatically rather than needing reconfiguration. +UI: — first visit creates the local admin account. Switching which llama.cpp model is active just means restarting the underlying `start-*.sh` script for the port you want live; Open WebUI already has both 8080 and 8081 registered as connections (see above), so it reconnects automatically rather than needing reconfiguration. Not yet ported to Windows (no Podman/Docker there currently). diff --git a/adr/0004-vulkan-backend.md b/adr/0004-vulkan-backend.md index 5ef0a31..bbceb02 100644 --- a/adr/0004-vulkan-backend.md +++ b/adr/0004-vulkan-backend.md @@ -5,7 +5,7 @@ ## Context -There is no discrete GPU anywhere in this setup — the only GPU-class compute device available is the Intel Iris Xe integrated GPU (see [docs/hardware.md](../docs/hardware.md)). Running models at usable speed on a 16GB machine requires real GPU offload rather than falling back to CPU-only inference. +There is no discrete GPU anywhere in this setup — the only GPU-class compute device available is the Intel Iris Xe iGPU (see [docs/hardware.md](../docs/hardware.md)). Running models at usable speed on a 16GB machine requires real GPU offload rather than falling back to CPU-only inference. ## Decision diff --git a/docs/architecture.md b/docs/architecture.md index b0158fd..260ce8a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -27,6 +27,10 @@ flowchart LR QwenU -->|Vulkan| GPU ``` +Static export of the diagram above, for viewers without Mermaid rendering: [`images/architecture.png`](images/architecture.png). + +![Architecture diagram](images/architecture.png) + ## Components - **`llama-server` (×2 registered, 1 running at a time)** — the inference engine, built from `llama.cpp` source with the Vulkan backend. Production (`start-qwen3.sh`, port `8080`) and an uncensored/blunt-mode variant (`start-qwen3-uncensored.sh`, port `8081`) both register as connections in Open WebUI, but only one process runs at once — combined Vulkan memory doesn't fit both simultaneously at their current context sizes (see [SETUP.md](../SETUP.md#qwen3-4b-instruct-2507-heretic-av2--uncensored-bluntdirect-assistant-start-qwen3-uncensoredsh-fedora-only)). Whichever port is live just shows up in Open WebUI's model picker. diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 0000000..2d3b34f --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,27 @@ +# Compatibility Matrix + +What this setup has actually been run against, not a general support statement. Sourced from [SETUP.md](../SETUP.md), [JOURNAL.md](../JOURNAL.md), and [hardware.md](hardware.md). Per [AGENTS.md](../AGENTS.md#documentation-standards), unmeasured values are left as `TODO` rather than guessed — if you run this setup on a version not listed here and confirm it works (or doesn't), see [CONTRIBUTING.md](../CONTRIBUTING.md) for how to report it. + +| Component | Tested version | Notes | +|---|---|---| +| Fedora | 44 | KDE Plasma spin, current daily driver. See [hardware.md](hardware.md). | +| Windows | TODO — edition/build not recorded | Origin OS, preserved on a separate NTFS partition. See [hardware.md](hardware.md#windows-vs-fedora). | +| Podman | TODO — Fedora 44's default repo version, exact version not recorded | Rootless, no daemon. See [architecture.md](architecture.md#design-decisions-worth-calling-out). | +| Open WebUI | `ghcr.io/open-webui/open-webui:main` (floating tag, not pinned) | Deployed via [`start-open-webui.sh`](../start-open-webui.sh). A `:main` tag means "whatever's current" — pin to a release tag if reproducibility matters more than staying current. | +| Open Terminal | `ghcr.io/open-webui/open-terminal:slim` (floating tag, not pinned) | Deployed via [`start-open-terminal.sh`](../start-open-terminal.sh). Same floating-tag caveat as above. | +| `llama.cpp` (Fedora) | Built from source, Vulkan backend (`GGML_VULKAN=ON`) | Commit/tag in use not currently recorded — see [hardware.md](hardware.md#why-models-and-llamacpp-arent-in-git). | +| `llama.cpp` (Windows) | Precompiled Vulkan release, upgraded b9305 → b10107 | See [benchmarks.md](benchmarks.md#build-upgrade-impact-windows-b9305--b10107) for the re-verification after upgrade. | +| Vulkan | TODO — SDK/driver version not recorded | Backend confirmed working via GPU-resident inference (low RSS) on both OSes; see [adr/0004-vulkan-backend.md](../adr/0004-vulkan-backend.md). | +| Intel graphics driver | TODO — Mesa/`i915` version not recorded | Relevant to the fence-timeout bug in [troubleshooting.md](troubleshooting.md#i915-igpu-fence-timeout--gpu-hangs); worth recording if that bug is ever revisited upstream. | +| Tailscale | 1.98.8 (Fedora, installed from Fedora's own repos) | See [SETUP.md](../SETUP.md) for the firewalld zone configuration needed alongside it. | + +## Why this exists + +Every fix and workaround in [troubleshooting.md](troubleshooting.md) is tied to a specific version combination, even where that version isn't pinned down precisely yet — a driver update, a Vulkan SDK bump, or an Open WebUI release could change or resolve any of them. This table exists so a future reader (including future-self) can tell whether a fix is still expected to apply, and so gaps (the `TODO`s above) are visible instead of silently assumed. + +## Related documents + +- [hardware.md](hardware.md) — the machine these versions run on +- [troubleshooting.md](troubleshooting.md) — issues tied to specific versions above +- [SETUP.md](../SETUP.md) — full flag-by-flag configuration +- [AGENTS.md](../AGENTS.md#documentation-standards) — why unmeasured values stay `TODO` instead of guessed diff --git a/docs/github-setup.md b/docs/github-setup.md new file mode 100644 index 0000000..9ab2696 --- /dev/null +++ b/docs/github-setup.md @@ -0,0 +1,57 @@ +# GitHub Repository Setup + +A checklist of the GitHub configuration that lives in repository settings, not in files — so it doesn't get lost between this repo and any future one. None of this affects how the setup runs; it only affects how the repository presents itself on GitHub. Everything here is done once via the GitHub web UI (Settings tab), not via a script. + +## Repository description + +The one-line summary shown under the repo name on GitHub and in search results. Keep it in sync with the README's tagline so the two never drift: + +> Dual-OS (Windows + Fedora) local LLM serving, built around llama.cpp — no discrete GPU, just an Intel iGPU and Vulkan. + +Set under **Settings → General → Description** (or the pencil icon next to the description on the repo home page). + +## Repository topics + +Topics drive GitHub's discovery/search — add them under the gear icon next to "About" on the repo home page. Suggested set, based on what this repo actually documents: + +`llama-cpp` `local-llm` `vulkan` `intel-iris-xe` `igpu` `open-webui` `self-hosted` `tailscale` `fedora` `podman` `local-inference` `on-device-ai` + +Prefer existing, already-searched-for topics over inventing new ones — check what similar repos use before adding a topic that has zero other adopters. + +## Social preview + +The image shown when this repo's link is shared (Slack, Twitter/X, Discord, etc.). Set under **Settings → General → Social preview**. GitHub's recommended size is 1280×640px. The architecture diagram ([`docs/images/architecture.png`](images/architecture.png)) or a real captured screenshot from [`docs/images/`](images/) (once populated, see [`docs/images/README.md`](images/README.md)) are the two natural candidates — pick whichever is legible at thumbnail size, since the diagram has more small text. + +## Homepage URL + +The link shown next to the description on the repo home page, set in the same **About** panel as topics. This repo has no hosted deployment (it documents a personal, single-machine setup), so leave it unset or point it at the LinkedIn write-up ([`linkedin-post.md`](../linkedin-post.md)) if a public link is wanted. + +## Release strategy + +There's no packaged artifact here — no binary, no library, nothing to version-pin a downstream consumer against. [`CHANGELOG.md`](../CHANGELOG.md) already tracks milestones as rough, non-semver versions (v1.0–v1.4). Two options if GitHub Releases are wanted anyway, purely for visibility: + +- **Tag milestone commits** matching the `CHANGELOG.md` versions (e.g. `v1.4`) and publish a GitHub Release per tag, with the corresponding changelog section pasted into the release notes. +- **Skip Releases entirely** and treat `CHANGELOG.md` + `JOURNAL.md` as the version history, since that's already true today and Releases would just duplicate it. + +Given this repo's philosophy (a running notebook, not a product), skipping Releases is the lower-maintenance default — only start tagging if a specific need comes up (e.g. linking a stable reference point from an external write-up). + +## Branch protection (optional) + +Not currently load-bearing for a single-maintainer repo, but worth enabling if collaborators are ever added: + +- Require pull requests before merging to `main` (no direct pushes). +- Require the docs-lint workflow (see [.github/workflows/](../.github/workflows/)) to pass before merging. +- Do **not** require approvals from a nonexistent second maintainer — that would just lock the repo, not add safety. + +Set under **Settings → Branches → Branch protection rules**. + +## Discussions (optional) + +GitHub Discussions (Settings → General → Features → Discussions) is a reasonable home for open-ended questions ("does this work on an AMD iGPU?") that don't fit the Issues templates in [`.github/ISSUE_TEMPLATE/`](../.github/ISSUE_TEMPLATE/) (bug reports, doc fixes, feature requests all assume something concrete to act on). Not enabled by default here — a personal-notebook repo with low traffic doesn't need a second channel alongside Issues until there's evidence people are actually asking open-ended questions. + +## Related documents + +- [CONTRIBUTING.md](../CONTRIBUTING.md) — the workflow contributors follow once the repo is configured +- [CHANGELOG.md](../CHANGELOG.md) — the version history a release strategy would draw from +- [README.md](../README.md) — the description/topics above should stay consistent with this +- [.github/workflows/](../.github/workflows/) — the CI check branch protection would gate on diff --git a/docs/hardware.md b/docs/hardware.md index f470693..5b23548 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -9,7 +9,7 @@ Read this table first — it tells you whether the rest of this repository appli | Component | Value | |-----------|-------| | CPU | Intel Core i5-12500H (4P+8E cores, 16 threads) | -| GPU | Intel Iris Xe (integrated — **no discrete GPU**) | +| GPU | Intel Iris Xe iGPU (**no discrete GPU**) | | RAM | 16GB (~7.4–9.8GB Vulkan-visible budget) | | OS | Fedora 44 (daily driver), Windows (origin, preserved) | | Inference backend | Vulkan, via `llama.cpp` built from source | @@ -52,4 +52,5 @@ Both directories exist locally once the setup steps in [SETUP.md](../SETUP.md) a - [benchmarks.md](benchmarks.md) — what this hardware actually achieves - [models.md](models.md) — models tested on this hardware, compared - [lessons-learned.md](lessons-learned.md) — practical findings this hardware's constraints produced +- [compatibility.md](compatibility.md) — exact tested OS/driver versions - [../adr/0001-fedora-over-windows.md](../adr/0001-fedora-over-windows.md) · [../adr/0004-vulkan-backend.md](../adr/0004-vulkan-backend.md) — the stable decisions this hardware drove diff --git a/docs/images/README.md b/docs/images/README.md index 5e4a360..c76157d 100644 --- a/docs/images/README.md +++ b/docs/images/README.md @@ -1,6 +1,8 @@ -# Screenshot placeholders +# Images -Every `.png` in this directory is a **blank placeholder** (solid neutral gray, no real UI content) — not a real screenshot. They exist so the [README](../../README.md)'s Screenshots section and any other markdown embedding them renders correctly instead of showing broken-image icons, while it's obvious from opening the file that no real capture has happened yet. +## Screenshot placeholders + +Every screenshot `.png` in this directory is a **blank placeholder** (solid neutral gray, no real UI content) — not a real screenshot. They exist so the [README](../../README.md)'s Screenshots section and any other markdown embedding them renders correctly instead of showing broken-image icons, while it's obvious from opening the file that no real capture has happened yet. Replace each file in place (keep the filename) with a real screenshot (PNG or JPG) as it's captured — no other changes needed, every reference already points at these paths. @@ -12,3 +14,9 @@ Replace each file in place (keep the filename) with a real screenshot (PNG or JP | `mobile.png` | Open WebUI accessed from a phone over the Tailscale tailnet | TODO — placeholder | | `open-terminal.png` | Open Terminal integration — the SYSTEM connection invoked from chat, or the Files/Terminal side panel | TODO — placeholder | | `settings.png` *(optional)* | Model Capabilities / Integrations settings pages referenced in [docs/troubleshooting.md](../troubleshooting.md) | TODO — placeholder | + +## Generated diagrams + +| File | What it is | Status | +|---|---|---| +| `architecture.png` | Static PNG export of the Mermaid diagram in [docs/architecture.md](../architecture.md), for viewers without Mermaid rendering | Generated — regenerate from the Mermaid source in that file if the diagram changes | diff --git a/docs/images/architecture.png b/docs/images/architecture.png new file mode 100644 index 0000000..4dbea2e Binary files /dev/null and b/docs/images/architecture.png differ diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bc48d40..0731f43 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -11,6 +11,7 @@ Structured writeups of real issues hit while building and running this setup, co **Cause**: the build needs a package named exactly `glslc` — not `glslangValidator`, which looks like the same shader compiler but isn't. Two further CMake dependencies are also required: `spirv-headers-devel` and `spirv-tools-devel`. **Solution**: install the correct package names before configuring: + ```bash sudo dnf install -y glslc spirv-headers-devel spirv-tools-devel ``` @@ -160,4 +161,5 @@ sudo dnf install -y glslc spirv-headers-devel spirv-tools-devel - [JOURNAL.md](../JOURNAL.md) — the full narrative account each entry above is condensed from - [architecture.md](architecture.md) — how these components fit together - [lessons-learned.md](lessons-learned.md) — the general takeaways drawn from these issues +- [compatibility.md](compatibility.md) — which versions each issue above was found on - [../adr/](../adr/) — the stable decisions behind why these components are in the stack at all diff --git a/linkedin-post.md b/linkedin-post.md index 66d8446..864275f 100644 --- a/linkedin-post.md +++ b/linkedin-post.md @@ -75,7 +75,7 @@ warning: failed to mlock 412090368-byte buffer: Cannot allocate memory $ ulimit -l 8192 -8MB cap, set by systemd's user@.service, not /etc/security/limits.conf like every search result claims. Fedora desktop sessions get their limits from systemd, not PAM. That one cost real time to track down. +8MB cap, set by systemd's `user@.service`, not `/etc/security/limits.conf` like every search result claims. Fedora desktop sessions get their limits from systemd, not PAM. That one cost real time to track down. Didn't fight it. Windows testing had already shown mlock gets risky under memory pressure on 16GB anyway. Both platforms run on plain mmap now. diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..af41508 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,17 @@ +# Config for the link-check job in .github/workflows/docs-lint.yml. +# Excludes targets that are expected to be unreachable in CI rather than +# broken: this machine's own loopback/Tailscale addresses (documented, not +# public), a templated placeholder hostname, and links into llama.cpp/ — +# an upstream checkout that's gitignored and never present in a fresh clone +# (see docs/hardware.md#why-models-and-llamacpp-arent-in-git). +exclude = [ + '^https?://localhost', + '^https?://127\.0\.0\.1', + '^https?://100\.', + '\.ts\.net', + '^mailto:', + 'llama\.cpp/AGENTS\.md$', + '(^|/)llama\.cpp$', +] + +exclude_all_private = true