From 7d2b8c562dc3b5fe4073111ba2655fa6da637c3a Mon Sep 17 00:00:00 2001 From: "dolgolyov.alexei" Date: Thu, 26 Mar 2026 21:57:23 +0300 Subject: [PATCH] docs: fix lint warnings and clean up references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- claude-code-tools.md | 8 +------- ecc-setup-guide.md | 31 ++++++++++++++++++++++++------- gitea-python-ci-cd.md | 19 ++++++++++--------- windows-code-signing.md | 15 ++++++++++++++- 4 files changed, 49 insertions(+), 24 deletions(-) diff --git a/claude-code-tools.md b/claude-code-tools.md index d463066..acaefa1 100644 --- a/claude-code-tools.md +++ b/claude-code-tools.md @@ -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 diff --git a/ecc-setup-guide.md b/ecc-setup-guide.md index f58c82b..4da0b27 100644 --- a/ecc-setup-guide.md +++ b/ecc-setup-guide.md @@ -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\\everything-claude-code cd C:\Users\\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 # Example: .\install.ps1 python typescript ``` **macOS/Linux (Bash):** + ```bash ./install.sh # Example: ./install.sh python typescript ``` **Cross-platform (npm):** + ```bash npx ecc-install ``` @@ -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\\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 ``` diff --git a/gitea-python-ci-cd.md b/gitea-python-ci-cd.md index 6756b21..e4c6a24 100644 --- a/gitea-python-ci-cd.md +++ b/gitea-python-ci-cd.md @@ -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=` (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) | diff --git a/windows-code-signing.md b/windows-code-signing.md index ce106f9..9f652d9 100644 --- a/windows-code-signing.md +++ b/windows-code-signing.md @@ -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/)