docs: add FAQ, troubleshooting guide, and README badges for v1.1.1

Addresses adoption-friction feedback on v1.1.0 (rated 8.0/10) by
filling three documentation gaps:

- README badge row (license, release, stars, top language, last commit)
- docs/faq.md with 10 first-time-user questions
- docs/troubleshooting.md with 12 symptom→cause→fix entries
- Documentation section in README linking all five doc pages

No code, schema, or command changes. Pure docs release.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MehmetGoekce

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2026-04-18
+
+### Added
+
+- README badge row — license, release, stars, top language, last commit
+- `docs/faq.md` — 10 questions first-time users actually ask (paid plan, L1/L2 rationale, tool choice, credential safety, wiki growth thresholds)
+- `docs/troubleshooting.md` — setup, wiki-app integration, Claude Code integration, and wiki-growth issues with symptom → cause → fix format
+- README "Documentation" section linking all five docs pages
+
+### Notes
+
+- Documentation-only release. No code, schema, or command changes.
+- Focus: adoption friction. The v1.1.0 feedback pointed at missing onboarding docs, not missing features.
+
 ## [1.1.0] - 2026-04-10
 
 ### Added
@@ -52,5 +66,6 @@ First stable release.
 - Credential leak detection (lint rule 6) scans for tokens, passwords, secrets
 - L1/L2 security boundary: credentials stay in L1 (git-excluded), wiki is git-tracked
 
+[1.1.1]: https://github.com/MehmetGoekce/llm-wiki/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/MehmetGoekce/llm-wiki/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/MehmetGoekce/llm-wiki/releases/tag/v1.0.0

README.md

@@ -1,5 +1,11 @@
 # llm-wiki
 
+[![License: MIT](https://img.shields.io/github/license/MehmetGoekce/llm-wiki)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/MehmetGoekce/llm-wiki)](https://github.com/MehmetGoekce/llm-wiki/releases)
+[![Stars](https://img.shields.io/github/stars/MehmetGoekce/llm-wiki?style=social)](https://github.com/MehmetGoekce/llm-wiki/stargazers)
+[![Top Language](https://img.shields.io/github/languages/top/MehmetGoekce/llm-wiki)](https://github.com/MehmetGoekce/llm-wiki)
+[![Last Commit](https://img.shields.io/github/last-commit/MehmetGoekce/llm-wiki)](https://github.com/MehmetGoekce/llm-wiki/commits)
+
 Build [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) with Claude Code. Two-layer cache architecture (L1/L2). Supports Logseq and Obsidian.
 
 ```mermaid
@@ -296,6 +302,14 @@ No system is perfect. Some things to know:
 - **Parallel agents can conflict.** If you have multiple Claude sessions writing to wiki files simultaneously, concurrent edits can cause conflicts. Treat wiki files as a shared resource.
 - **Start with fewer hub pages.** Let them emerge organically from ingest operations rather than creating empty hubs upfront.
 
+## Documentation
+
+- [FAQ](docs/faq.md) — Common questions before you run `setup.sh`
+- [Troubleshooting](docs/troubleshooting.md) — Setup, integration, and runtime issues
+- [L1/L2 Architecture](docs/l1-l2-architecture.md) — Why two layers, how to route knowledge
+- [Schema Reference](docs/schema-reference.md) — Page types, properties, lint rules
+- [Logseq vs. Obsidian](docs/logseq-vs-obsidian.md) — Detailed comparison and migration notes
+
 ## Credits
 
 - Inspired by [Andrej Karpathy's LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

docs/faq.md

@@ -0,0 +1,92 @@
+# Frequently Asked Questions
+
+Questions that come up when evaluating whether llm-wiki is the right tool for you.
+
+## What does llm-wiki actually do that a plain Logseq or Obsidian setup doesn't?
+
+A plain Logseq or Obsidian setup is a manual knowledge base. You decide what to capture, you write the pages, you maintain the links, and you fix the inconsistencies. The quality of the wiki degrades as your effort drops.
+
+llm-wiki turns Claude Code into the wiki maintainer. You feed it raw sources (URLs, files, chat transcripts), and it extracts entities, creates or updates 5-15 pages per ingest, adds cross-references between them, and enforces a schema so every page follows the same structure. A `/wiki lint` command continuously checks for broken links, stale content, missing properties, and credential leaks.
+
+The wiki app (Logseq or Obsidian) is still where you *read* the knowledge. The difference is who does the writing.
+
+## Do I need a paid Claude plan?
+
+Yes. llm-wiki assumes you are using [Claude Code](https://claude.ai/code), which requires an Anthropic account and a paid plan (Pro or higher). All `/wiki` commands run through Claude Code — there are no external API calls, no vector databases, no separate ingest servers.
+
+Claude Code itself is the only dependency. There is no additional cost for llm-wiki beyond your existing Claude plan.
+
+## Why two layers (L1 and L2)? Isn't one enough?
+
+If everything lives in one place, you face a dilemma: either the LLM loads the entire wiki into every session (blowing up the context window) or it queries the wiki per question (too slow for simple rules like "always use ISO 8601 dates").
+
+Splitting knowledge into L1 (auto-loaded, always present) and L2 (on-demand) solves this. Operational rules and gotchas live in L1. Deep project knowledge lives in L2. The LLM has instant access to both, but the context window stays lean.
+
+It feels overengineered at first. After a week of use, the boundary becomes second nature. See [docs/l1-l2-architecture.md](l1-l2-architecture.md) for the full rationale.
+
+## Logseq or Obsidian — which should I choose?
+
+If you already use one, stick with it. llm-wiki supports both equally, and migration between them is not trivial (different file-naming conventions).
+
+If you are starting fresh, the short version:
+
+- **Logseq** for LLM-heavy workflows. Outliner format means every line is an addressable block, so the LLM can append without disturbing existing structure.
+- **Obsidian** for human-heavy workflows. Flat markdown is nicer to read and edit by hand, and the plugin ecosystem is huge.
+
+See [docs/logseq-vs-obsidian.md](logseq-vs-obsidian.md) for the full comparison.
+
+## Can I ingest my existing notes?
+
+Yes, but not with a single command yet. For now:
+
+1. Run `./setup.sh` to create the schema and namespace structure in a fresh wiki location.
+2. Use `/wiki ingest <path-to-existing-note>` to process notes one at a time. The LLM extracts entities, fits them into your schema, and creates cross-references.
+3. Iterate — Claude will ask clarifying questions for ambiguous content.
+
+Bulk migration tooling is on the roadmap. For now, ingesting 20-50 notes manually is the common path.
+
+## Can I use this with ChatGPT or Gemini instead of Claude?
+
+Not currently. The `/wiki` commands rely on Claude Code's skill system and memory architecture. The ingest pipeline, lint rules, and query synthesis are specified against Claude's behavior.
+
+Porting to other CLI-based LLM coding tools is on the roadmap but requires significant work — not just the command layer, but the L1 memory semantics and the append-only page discipline.
+
+## What is the difference between this and Karpathy's original gist?
+
+Karpathy's gist is a concept essay. It describes *what* an LLM wiki should do (ingest, query, lint) and why it matters. It does not specify tools, file formats, schemas, or workflows.
+
+llm-wiki is an implementation. It picks Claude Code as the LLM, Logseq or Obsidian as the wiki UI, defines a concrete schema with 5 page types, specifies 9 lint rules with auto-fix behavior, and adds the L1/L2 cache layer that the gist does not mention. Setup takes 5 minutes with `./setup.sh`; the gist is 100% design, 0% code.
+
+If you want the pure concept, read the gist. If you want a working system, use llm-wiki.
+
+## At what wiki size does this become worth the overhead?
+
+The schema and lint rules feel like overhead at under 20 pages — you could maintain 20 notes by hand. Past 50 pages, the structure starts paying for itself. Past 200, maintaining the wiki without automation is essentially impossible.
+
+The useful mental model: set up llm-wiki when you expect to cross 50 pages within 6 months. Below that threshold, plain notes are fine.
+
+## How do I prevent credentials from ending up in the wiki?
+
+Credentials must live in L1 (Claude Code memory), never in L2 (the wiki). The wiki is typically git-tracked, which means anything in L2 could be published accidentally.
+
+Three layers of protection:
+
+1. **Schema rule.** The schema explicitly states credentials go in L1 only.
+2. **Lint rule #6 (credential-leak).** `/wiki lint` scans every page for `token::`, `password::`, `secret::`, `api-key::`, and base64 patterns. Critical severity — blocks commits.
+3. **Ingest quality gate.** Phase 4 of the ingest pipeline aborts before writing if credentials are detected in the extracted content.
+
+If a credential slips through despite this, `/wiki lint --fix` will flag it and refuse to auto-repair (so it does not remove it silently). You remove it manually, rotate the credential, and move the reference to L1.
+
+## How do I commit the wiki to GitHub safely?
+
+Three checks before your first push:
+
+1. **Run `/wiki lint` and confirm zero credential warnings.** Critical severity issues must be resolved first.
+2. **Verify your memory directory is in `.gitignore`.** The Claude Code `memory/` path (typically `~/.claude/projects/*/memory/`) must be excluded — it contains credentials and personal data.
+3. **Review the first commit diff manually.** One-time sanity check that no API tokens or personal notes made it into tracked files.
+
+After the first push, the L1/L2 boundary enforces itself. The lint runs catch drift before it reaches GitHub.
+
+## Where do I report bugs or request features?
+
+[GitHub Issues](https://github.com/MehmetGoekce/llm-wiki/issues) — there are templates for bug reports and feature requests. Security issues: see [SECURITY.md](../SECURITY.md).

docs/troubleshooting.md

@@ -0,0 +1,157 @@
+# Troubleshooting
+
+Common issues and fixes. If your problem is not listed here, open a [GitHub issue](https://github.com/MehmetGoekce/llm-wiki/issues/new/choose).
+
+## Setup
+
+### `setup.sh: python3: command not found`
+
+**Cause:** Python 3 is not installed or not in your `PATH`. The setup script uses Python 3 to render page templates.
+
+**Fix:**
+
+- **macOS:** `brew install python3`
+- **Ubuntu/Debian:** `sudo apt install python3`
+- **Fedora:** `sudo dnf install python3`
+- **Windows:** Install from [python.org](https://www.python.org/downloads/) and check "Add python.exe to PATH" during install.
+
+Verify with `python3 --version`. The script requires Python 3.6 or newer (any version from the last ~8 years works).
+
+### `setup.sh: git: command not found`
+
+**Cause:** Git is not installed. Needed for the optional `git init` step and to clone the repo in the first place.
+
+**Fix:**
+
+- **macOS:** Comes with Xcode Command Line Tools — run `xcode-select --install`.
+- **Ubuntu/Debian:** `sudo apt install git`
+- **Fedora:** `sudo dnf install git`
+- **Windows:** Install [Git for Windows](https://git-scm.com/download/win).
+
+### `setup.sh` fails during template rendering
+
+**Cause:** Usually one of three things:
+
+1. The destination directory is not writable.
+2. The template directory is missing (corrupted clone or wrong working directory).
+3. A pre-existing file blocks template output.
+
+**Fix:**
+
+- Confirm you ran `./setup.sh` from inside the cloned `llm-wiki` directory, not from elsewhere.
+- Check the path you entered is writable: `touch ~/Documents/Logseq/test.txt && rm ~/Documents/Logseq/test.txt`.
+- If pre-existing pages block the render, setup will skip them. Delete the skipped pages manually if you want them regenerated.
+- Re-clone the repo if `templates/` looks empty or partial.
+
+### The script exits at "Which note-taking tool do you use?"
+
+**Cause:** Something other than `1` or `2` was entered. The script exits immediately on invalid input rather than re-prompting.
+
+**Fix:** Re-run `./setup.sh` and enter exactly `1` (Logseq) or `2` (Obsidian). If you prefer non-interactive runs (e.g., CI or testing):
+
+```bash
+echo -e "1\n~/test-wiki\ny\n\nskip\ny\nskip" | ./setup.sh
+```
+
+See `CONTRIBUTING.md` for the full stdin sequence.
+
+## Wiki App Integration
+
+### New pages don't appear in the Logseq graph
+
+**Cause:** Logseq watches the `pages/` directory but only re-indexes under specific conditions. New files created while Logseq is running may not show up until you reload.
+
+**Fix:**
+
+1. In Logseq: `File → Reindex` (or `Cmd/Ctrl + Shift + R`).
+2. Confirm the file path is correct. Logseq pages live in `<graph-root>/pages/` and must use the `Wiki___Namespace___Page.md` triple-underscore naming.
+3. Check `journals/` is not accidentally being used — journals have a different format and will not render as regular wiki pages.
+
+### Obsidian shows YAML frontmatter as a code block instead of Properties
+
+**Cause:** Older Obsidian versions (before 1.4, released mid-2023) do not support the Properties feature. The frontmatter still works, but renders as literal text.
+
+**Fix:**
+
+- Update Obsidian to the latest version.
+- In Settings → Editor, ensure "Properties in document" is enabled.
+- If you deliberately disable Properties, the wiki still works — the LLM reads the YAML, and nothing breaks. The display is just uglier.
+
+### Cross-references `[[Wiki/Tech/Strapi]]` aren't clickable
+
+**Cause:** Wrong file-naming convention for the tool.
+
+**Fix:**
+
+- **Logseq** expects triple-underscore flat files: `Wiki___Tech___Strapi.md`. `[[Wiki/Tech/Strapi]]` resolves because Logseq treats `/` and `___` as equivalent path separators.
+- **Obsidian** expects directory hierarchy: `Wiki/Tech/Strapi.md`. The file literally lives inside `Wiki/Tech/`.
+
+If you mix conventions (e.g., triple-underscore files inside an Obsidian vault), links break. Check that `setup.sh` configured the correct tool — run it again and pick the tool matching your current vault.
+
+## Claude Code Integration
+
+### `/wiki` commands aren't available in Claude Code
+
+**Cause:** The skill was not installed into your project. `setup.sh` offers to copy it but it is optional.
+
+**Fix:**
+
+1. Confirm `.claude/commands/wiki.md` exists in your project directory.
+2. If missing, re-run `./setup.sh` and answer `y` at the "Install wiki skill in a project?" step, then provide the project path.
+3. Alternatively, copy manually:
+   ```bash
+   cp wiki.md ~/your-project/.claude/commands/wiki.md
+   ```
+4. In `wiki.md`, verify the `<CONFIG_PATH>` placeholder has been replaced with the absolute path to your `llm-wiki.yml`.
+
+Restart Claude Code for the skill to be picked up.
+
+### `/wiki ingest` runs forever or times out
+
+**Cause:** Source is too large, or the wiki has grown past the batch limit and Claude is trying to load too many pages at once.
+
+**Fix:**
+
+- Split large sources. A 10,000-word document should be ingested in 2-3 passes, not one.
+- The ingest pipeline has a 3-page batch limit — if your wiki has hundreds of pages and many are relevant to the source, processing takes proportionally longer.
+- If Claude Code hits a context limit mid-ingest, it will stop and report. Re-run the same ingest — Claude's append-only discipline prevents duplicates.
+
+### `/wiki ingest` blocks with a credential-leak warning but the content has no credentials
+
+**Cause:** False positive from lint rule #6. The credential-leak regex includes base64-like patterns (`[A-Za-z0-9+/]{40,}`), which also match innocent long strings — long URLs, hashes, or technical identifiers.
+
+**Fix:**
+
+1. Review the flagged content. If it is a genuine credential, move it to L1 (memory) and strip it from the source before re-ingesting.
+2. If it is a false positive (e.g., a commit SHA or a long URL), you have two options:
+   - Edit the source to break the pattern (e.g., add a space or truncate).
+   - Temporarily disable the base64 pattern in `llm-wiki.yml` → `lint.credential_patterns`. Re-enable it after the ingest.
+
+Never commit around the lint by force. The false positive rate is low, and genuine credential leaks have serious consequences.
+
+## Wiki Growth
+
+### The wiki has grown past 200 pages and feels unmanageable
+
+**Cause:** Natural friction at scale. Past ~200 pages, flat namespaces get noisy, hub pages grow long, and the mental model of "what is where" breaks down.
+
+**Fix:**
+
+- **Split namespaces.** If `Wiki/Tech/` has 50+ pages, consider splitting into `Wiki/Tech/Infrastructure/`, `Wiki/Tech/Languages/`, etc. Namespaces can go 3 levels deep.
+- **Consolidate hubs.** A hub page with 40 child links is useless. Group children into sub-sections with brief descriptions, not just a flat list.
+- **Run `/wiki lint` weekly.** Stale detection reveals pages that have not been updated in 90+ days — candidates for archival or deletion.
+- **Audit L1/L2.** If you find yourself querying the same L2 page every session, promote the essential part to L1.
+
+The wiki scales, but like any knowledge system, it requires periodic gardening.
+
+### `/wiki lint` keeps flagging the same orphan pages
+
+**Cause:** Pages that have no incoming links are flagged as orphans. If the same pages appear every run, they are genuinely unlinked.
+
+**Fix:**
+
+- Add the page to the appropriate hub page (e.g., `Wiki/Tech` hub should list all `Wiki/Tech/*` pages).
+- Add cross-references from related pages — if `Wiki/Projects/X` mentions `Wiki/Tech/Y`, make sure it uses `[[Wiki/Tech/Y]]` syntax.
+- Run `/wiki lint --fix` — it auto-adds missing hub entries where obvious.
+
+If a page is genuinely isolated and cannot be linked from anywhere, it may be a sign the page is misplaced (wrong namespace) or should be deleted.