docs: fix lint warnings and clean up references

- Fix MD060 table separator spacing across all docs - Fix MD031/MD032 blank lines around code fences and lists - Fix MD029 ordered list numbering in ecc-setup-guide - Genericize hardcoded app names (LedGrab/MediaServer → YourApp) - Remove non-existent `claude skill install` CLI command - Add staleness warning for ECC Windows fixes - Add cross-link from windows-code-signing to gitea-python-ci-cd
2026-03-26 21:57:23 +03:00
parent 1ed06d54c4
commit 7d2b8c562d
4 changed files with 49 additions and 24 deletions
@@ -27,13 +27,7 @@ Skills are a different extension mechanism from MCPs. They are prompt-based exte

 Skills are distributed as `.skill` files (ZIP archives containing a `SKILL.md` and optional scripts).

-**Option 1 — CLI** (if `claude` command is available):
-
-```bash
-claude skill install --scope user my-skill.skill
-```
-
-**Option 2 — Manual extraction** (works everywhere, including VS Code extension):
+**Manual extraction** (works everywhere, including VS Code extension):

 ```bash
 # Python one-liner
@@ -2,6 +2,8 @@

 Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.

+> **Staleness warning:** The Windows-specific fixes (gotchas 6–8) were documented against ECC as of early 2026. These bugs may have been fixed upstream — check the [ECC repository](https://github.com/affaan-m/everything-claude-code) for recent changes before applying the workarounds.
+
 ## Prerequisites

 - Node.js + npm installed
@@ -12,6 +14,7 @@ Step-by-step instructions for setting up ECC on a new machine. Can be followed m
 ## Step 1 — Clone and install

 **Windows (PowerShell):**
+
 ```powershell
 git clone https://github.com/affaan-m/everything-claude-code.git C:\Users\<USERNAME>\everything-claude-code
 cd C:\Users\<USERNAME>\everything-claude-code
@@ -19,6 +22,7 @@ npm install
 ```

 **macOS/Linux (Bash):**
+
 ```bash
 git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code
 cd ~/everything-claude-code
@@ -30,18 +34,21 @@ npm install
 Run the installer **from inside the cloned repo**.

 **Windows (PowerShell):**
+
 ```powershell
 .\install.ps1 <languages>
 # Example: .\install.ps1 python typescript
 ```

 **macOS/Linux (Bash):**
+
 ```bash
 ./install.sh <languages>
 # Example: ./install.sh python typescript
 ```

 **Cross-platform (npm):**
+
 ```bash
 npx ecc-install <languages>
 ```
@@ -55,7 +62,7 @@ Available languages: `python`, `typescript`, `golang`, `swift`, `php`, `rust`, `
 All files go to `~/.claude/` (global, applies to all projects):

 | Category | Location | Examples |
-|----------|----------|---------|
+| ---------- | ---------- | --------- |
 | Rules | `~/.claude/rules/` | coding-style, testing, security (per language) |
 | Agents | `~/.claude/agents/` | planner, architect, code-reviewer, tdd-guide, security-reviewer |
 | Skills | `~/.claude/skills/` | python-patterns, tdd-workflow, e2e-testing, continuous-learning |
@@ -67,14 +74,18 @@ All files go to `~/.claude/` (global, applies to all projects):
 Some agents (planner, architect) ship with only `Read, Grep, Glob` tools. To enable `ast-index` and other CLI tools, add `Bash` to their tool lists.

 Edit these files in `~/.claude/agents/`:
+
 - `planner.md`
 - `architect.md`

 Change the frontmatter `tools` line from:
+
 ```yaml
 tools: ["Read", "Grep", "Glob"]
 ```
+
 To:
+
 ```yaml
 tools: ["Read", "Grep", "Glob", "Bash"]
 ```
@@ -131,7 +142,7 @@ Hooks and new agents only take effect after restarting Claude Code.
 Run these commands inside Claude Code to verify:

 | Command | Expected result |
-|---------|----------------|
+| --------- | ---------------- |
 | `/plan "test"` | Should invoke the planner agent |
 | `/instinct-status` | Should show instinct status (empty on first run) |
 | `/code-review` | Should invoke the code-reviewer agent |
@@ -139,7 +150,7 @@ Run these commands inside Claude Code to verify:
 ## Useful commands

 | Command | Purpose |
-|---------|---------|
+| --------- | --------- |
 | `/plan` | Create implementation plan before coding |
 | `/tdd` | Test-driven development workflow |
 | `/code-review` | Review code for quality issues |
@@ -166,11 +177,11 @@ Run these commands inside Claude Code to verify:

 The observe hook ships with three bugs that silently prevent all observations on Windows:

-6. **`python3` is the Windows Store stub** — On Windows, `python3` resolves to the Microsoft Store redirect (`AppData/Local/Microsoft/WindowsApps/python3`) which returns exit code 49 instead of running Python. The hook's `resolve_python_cmd()` uses `command -v` which finds the stub. **Fix:** In both `~/.claude/skills/continuous-learning-v2/hooks/observe.sh` and `~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh`, change `resolve_python_cmd()` to test execution (`"$candidate" -c "1"`) instead of just checking presence (`command -v`).
+1. **`python3` is the Windows Store stub** — On Windows, `python3` resolves to the Microsoft Store redirect (`AppData/Local/Microsoft/WindowsApps/python3`) which returns exit code 49 instead of running Python. The hook's `resolve_python_cmd()` uses `command -v` which finds the stub. **Fix:** In both `~/.claude/skills/continuous-learning-v2/hooks/observe.sh` and `~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh`, change `resolve_python_cmd()` to test execution (`"$candidate" -c "1"`) instead of just checking presence (`command -v`).

-7. **`claude-vscode` entrypoint rejected** — The hook's Layer 1 filter only allows `cli` and `sdk-ts` entrypoints. VS Code extension sets `CLAUDE_CODE_ENTRYPOINT=claude-vscode`, so every observation is silently skipped. **Fix:** Add `claude-vscode` to the allowed entrypoints case pattern in `observe.sh`.
+2. **`claude-vscode` entrypoint rejected** — The hook's Layer 1 filter only allows `cli` and `sdk-ts` entrypoints. VS Code extension sets `CLAUDE_CODE_ENTRYPOINT=claude-vscode`, so every observation is silently skipped. **Fix:** Add `claude-vscode` to the allowed entrypoints case pattern in `observe.sh`.

-8. **Observer disabled by default** — `~/.claude/skills/continuous-learning-v2/config.json` ships with `"enabled": false`. **Fix:** Set `"enabled": true`.
+3. **Observer disabled by default** — `~/.claude/skills/continuous-learning-v2/config.json` ships with `"enabled": false`. **Fix:** Set `"enabled": true`.

 ## Step 6 — Configure agent model tiers

@@ -179,12 +190,13 @@ ECC agents ship with `sonnet` as default. For better results, set thinking-heavy
 Edit the `model:` line in each agent's frontmatter in `~/.claude/agents/`:

 | Model | Agents | Rationale |
-|-------|--------|-----------|
+| ------- | -------- | ----------- |
 | **opus** | code-reviewer, python-reviewer, typescript-reviewer, rust-reviewer, go-reviewer, java-reviewer, kotlin-reviewer, cpp-reviewer, flutter-reviewer, database-reviewer, security-reviewer, tdd-guide, planner, architect, chief-of-staff | Deep reasoning for code quality, security, architecture |
 | **sonnet** | build-error-resolver, cpp-build-resolver, go-build-resolver, java-build-resolver, kotlin-build-resolver, rust-build-resolver, pytorch-build-resolver, e2e-runner, harness-optimizer, loop-operator, docs-lookup, refactor-cleaner | Mechanical tasks, error fixing |
 | **haiku** | doc-updater | Lightweight docs work |

 To bulk-update reviewers and thinking-heavy agents to opus:
+
 ```bash
 # From bash/git bash:
 for f in ~/.claude/agents/{code,python,typescript,rust,go,java,kotlin,cpp,flutter,database,security}-reviewer.md ~/.claude/agents/tdd-guide.md; do
@@ -201,6 +213,7 @@ The installer overwrites all files in `~/.claude/`, so updating is straightforwa
 **1. Pull the latest version:**

 **Windows (PowerShell):**
+
 ```powershell
 cd C:\Users\<USERNAME>\everything-claude-code
 git pull
@@ -208,6 +221,7 @@ npm install
 ```

 **macOS/Linux (Bash):**
+
 ```bash
 cd ~/everything-claude-code
 git pull
@@ -215,6 +229,7 @@ npm install
 ```

 **2. Back up your customizations:**
+
 ```bash
 # Save agent model overrides
 grep -l 'model: opus' ~/.claude/agents/*.md > /tmp/ecc-opus-agents.txt
@@ -228,11 +243,13 @@ cp ~/.claude/skills/continuous-learning-v2/config.json /tmp/cl-config.json.bak
 **3. Re-run the installer:**

 **Windows (PowerShell):**
+
 ```powershell
 .\install.ps1 python typescript
 ```

 **macOS/Linux (Bash):**
+
 ```bash
 ./install.sh python typescript
 ```
@@ -5,7 +5,7 @@ A reusable reference for building CI pipelines, release automation, and installe
 **This is a modular reference — pick only the sections you need.** Not every project requires all build targets. Common combinations:

 | Project type | Sections to use |
-|---|---|
+| --- | --- |
 | Docker-only service | 1, 2 (docker job only), 7, 8 |
 | Desktop app (Windows + Linux) | 1, 2, 3, 4, 5, 6, 8 |
 | Desktop + Docker | All sections |
@@ -636,6 +636,7 @@ git push origin v0.2.0-alpha.1
 Instead of hardcoding release notes in the workflow, keep a `RELEASE_NOTES.md` in the repo root. The CI fetches only that file (via sparse-checkout for speed) and prepends its content to the auto-generated Downloads section.

 **Workflow:**
+
 1. Before tagging, write `RELEASE_NOTES.md` with changes for this release
 2. Commit, tag, push — CI picks up the file automatically
 3. Release body = your notes + auto-generated download/Docker instructions
@@ -833,7 +834,7 @@ Examples: `v0.3.0-alpha.1` → `0.3.0a1`, `v0.3.0-rc.3` → `0.3.0rc3`, `v1.0.0`
 Detect at startup by checking filesystem markers:

 | Marker | Install type | Auto-update strategy |
-|--------|-------------|---------------------|
+| -------- | ------------- | --------------------- |
 | `uninstall.exe` in CWD | `installer` | Download `-setup.exe`, run `/S /D=<dir>` (silent NSIS reinstall) |
 | `python/python.exe` in CWD (no uninstaller) | `portable` (Windows) | Download ZIP, extract, swap `app/` + `python/` via detached bat script |
 | `venv/` + `run.sh` in CWD | `portable` (Linux) | Download tarball, extract, swap `app/` + `venv/` via detached shell script |
@@ -875,9 +876,9 @@ Can't replace files while the server is running (DLL locks). Solution: write a `
@echo off
 timeout /t 5 /nobreak >nul
 rmdir /s /q "C:\path\app" 2>nul
-move /y "C:\path\staging\LedGrab\app" "C:\path\app"
+move /y "C:\path\staging\YourApp\app" "C:\path\app"
 rmdir /s /q "C:\path\python" 2>nul
-move /y "C:\path\staging\LedGrab\python" "C:\path\python"
+move /y "C:\path\staging\YourApp\python" "C:\path\python"
 rmdir /s /q "C:\path\staging" 2>nul
 start "" wscript.exe "C:\path\scripts\start-hidden.vbs"
 del /f /q "%~f0"
@@ -892,8 +893,8 @@ Same pattern but with a shell script:
 ```bash
 #!/bin/bash
 sleep 3
-rm -rf "$APP_ROOT/app" && mv "$STAGING/LedGrab/app" "$APP_ROOT/app"
-rm -rf "$APP_ROOT/venv" && mv "$STAGING/LedGrab/venv" "$APP_ROOT/venv"
+rm -rf "$APP_ROOT/app" && mv "$STAGING/YourApp/app" "$APP_ROOT/app"
+rm -rf "$APP_ROOT/venv" && mv "$STAGING/YourApp/venv" "$APP_ROOT/venv"
 rm -rf "$STAGING"
 cd "$APP_ROOT" && exec ./run.sh
 ```
@@ -901,7 +902,7 @@ cd "$APP_ROOT" && exec ./run.sh
 ### 11.7. API Endpoints

 | Method | Path | Purpose |
-|--------|------|---------|
+| -------- | ------ | --------- |
 | `GET` | `/system/update/status` | Current state, available version, install type, progress |
 | `POST` | `/system/update/check` | Trigger immediate check |
 | `POST` | `/system/update/dismiss` | Dismiss notification for a version |
@@ -965,13 +966,13 @@ bash build-dist-windows.sh v1.0.0

 # 3. Build NSIS installer
 "/c/Program Files (x86)/NSIS/makensis.exe" -DVERSION="1.0.0" installer.nsi
-# Output: build/MediaServer-v1.0.0-setup.exe
+# Output: build/YourApp-v1.0.0-setup.exe
 ```

 ### 13.3. Common Issues

 | Issue | Cause | Fix |
-|-------|-------|-----|
+| ------- | ------- | ----- |
 | `zip: command not found` | Git Bash doesn't include `zip` | Harmless — only affects the portable ZIP, not the installer. Install `zip` via MSYS2 if needed |
 | `Exec expects 1 parameters, got 2` | `MUI_FINISHPAGE_RUN_PARAMETERS` quoting breaks NSIS `Exec` | Use `MUI_FINISHPAGE_RUN_FUNCTION` instead (see section 6) |
 | `Error opening file for writing: ...python\\_asyncio.pyd` | Server is running and has DLLs locked | Stop the server before installing. Add `.onInit` file-lock check (see section 6) |
@@ -5,6 +5,7 @@ A review of code signing options for Windows executables (.exe installers), focu
 ## Why Sign?

 Unsigned executables trigger:
+
 - **Chrome**: "This file isn't commonly downloaded and may be dangerous"
 - **SmartScreen**: "Windows protected your PC — Unknown publisher"
 - **Edge**: Download blocked with "unverified" warning
@@ -18,6 +19,7 @@ These warnings significantly reduce user trust and installation rates.
 **Cost:** ~$9.99/month (Basic tier)

 **Key advantages:**
+
 - **Immediate SmartScreen trust** — Microsoft is the CA, so signed binaries are trusted from day one
 - Available to **individuals** — no business entity required
 - Identity verification via government ID + address (takes a few business days)
@@ -25,6 +27,7 @@ These warnings significantly reduce user trust and installation rates.
 - Microsoft-backed trust chain

 **Setup:**
+
 1. Create Azure account + subscription
 2. Provision "Trusted Signing" resource in Azure portal
 3. Complete identity verification (personal or organization)
@@ -53,6 +56,7 @@ These warnings significantly reduce user trust and installation rates.
 ```

 **Required secrets:**
+
 - `AZURE_KEY_VAULT_URL` — Trusted Signing account endpoint
 - `AZURE_CERT_NAME` — Certificate profile name
 - `AZURE_CLIENT_ID` — Azure AD app registration client ID
@@ -60,6 +64,7 @@ These warnings significantly reduce user trust and installation rates.
 - `AZURE_TENANT_ID` — Azure AD tenant ID

 **Gotchas:**
+
 - Identity verification can take a few business days
 - Basic tier shows your verified personal name (not a custom organization name)
 - Relatively new service — documentation is still evolving
@@ -72,6 +77,7 @@ These warnings significantly reduce user trust and installation rates.
 **Cost:** Free for qualifying open-source projects.

 **Requirements:**
+
 - OSI-approved license
 - **Public repository on a major forge** (GitHub, GitLab) — self-hosted Gitea likely does not qualify
 - Project must show community activity (stars, contributors, issues)
@@ -90,6 +96,7 @@ These warnings significantly reduce user trust and installation rates.
 **Cost:** OV ~$200-350/year, EV ~$350-500/year + eSigner cloud signing costs.

 **Key facts:**
+
 - Free open-source program **discontinued** as of late 2024
 - CA/Browser Forum rules (June 2023) require hardware token or cloud key storage — no PFX file downloads
 - eSigner cloud service has CLI tools and API, works with any CI
@@ -104,6 +111,7 @@ These warnings significantly reduce user trust and installation rates.
 **Cost:** ~$27-59/year for open-source OV code signing (cheapest legitimate option).

 **Key facts:**
+
 - Requires hardware token (SimplySign cloud or physical card reader)
 - SimplySign cloud option can work in CI with effort
 - OV only — SmartScreen reputation must be built over time
@@ -127,7 +135,7 @@ These warnings significantly reduce user trust and installation rates.
 ## Comparison Table

 | Option | Cost | SmartScreen | CI/CD Fit | Individual OK? |
-|--------|------|-------------|-----------|----------------|
+| -------- | ------ | ------------- | ----------- | ---------------- |
 | **Azure Trusted Signing** | $9.99/mo | Immediate | Excellent | Yes |
 | SignPath.io | Free | Immediate | GitHub only | Yes (if public repo) |
 | SSL.com OV | ~$250/yr | Needs reputation | Good (eSigner) | Yes |
@@ -138,6 +146,7 @@ These warnings significantly reduce user trust and installation rates.
 ## Recommendation

 **Azure Trusted Signing** is the best option for personal open-source projects:
+
 - Affordable ($9.99/mo)
 - Immediate SmartScreen trust
 - No business entity required
@@ -145,6 +154,10 @@ These warnings significantly reduce user trust and installation rates.

 If budget is zero and the project is on public GitHub, try **SignPath.io** first.

+## See Also
+
+- [CI/CD for Python Apps on Gitea](gitea-python-ci-cd.md) — full pipeline reference including the signing step in context
+
 ## References

 - [Azure Trusted Signing documentation](https://learn.microsoft.com/en-us/azure/trusted-signing/)