{"id":26926073,"url":"https://github.com/mlorentedev/dotfiles","last_synced_at":"2026-06-28T03:04:08.429Z","repository":{"id":283918059,"uuid":"882120129","full_name":"mlorentedev/dotfiles","owner":"mlorentedev","description":"Here are my personal configuration files. Customizations, themes, and settings for Linux.","archived":false,"fork":false,"pushed_at":"2026-03-26T20:57:00.000Z","size":733,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-26T23:43:45.099Z","etag":null,"topics":["bash","dotfiles","linux"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlorentedev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-01T23:51:35.000Z","updated_at":"2026-03-26T20:57:04.000Z","dependencies_parsed_at":"2025-06-14T16:35:48.493Z","dependency_job_id":null,"html_url":"https://github.com/mlorentedev/dotfiles","commit_stats":null,"previous_names":["mlorentedev/dotfiles"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mlorentedev/dotfiles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fdotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fdotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fdotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fdotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlorentedev","download_url":"https://codeload.github.com/mlorentedev/dotfiles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fdotfiles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31669116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","dotfiles","linux"],"created_at":"2025-04-02T03:30:17.017Z","updated_at":"2026-06-28T03:04:08.419Z","avatar_url":"https://github.com/mlorentedev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dotfiles\n\nPersonal development environment: shell configs, AI tool integration, and encrypted secrets management. Supported today on **Linux** and **Windows**. **macOS is planned** (roadmap) — there is no `setup-macos.sh` yet, so the Linux bootstrap is unverified on macOS.\n\n| Platform | Status | Bootstrap |\n|---|---|---|\n| Linux | Supported | `setup-linux.sh` |\n| Windows | Supported | `setup-windows.ps1` |\n| macOS | Planned (not yet implemented) | — |\n\n## Quick Start\n\n### Linux\n\n```bash\ngit clone https://github.com/mlorentedev/dotfiles.git ~/.dotfiles\ncd ~/.dotfiles\n./setup-linux.sh\nsource ~/.zshrc\n```\n\n### Windows (PowerShell)\n\n```powershell\ngit clone https://github.com/mlorentedev/dotfiles.git\ncd dotfiles\npowershell -ExecutionPolicy Bypass -File .\\setup-windows.ps1\n# Restart PowerShell after setup\n```\n\nOptional: add `-WithDefaults` to also apply ~15 HKCU engineering defaults\n(show file extensions/hidden files, disable advertising ID and Bing-in-Start,\ndark mode — the [mathiasbynens `.macos`](https://github.com/mathiasbynens/dotfiles/blob/main/.macos)\nanalog, see `scripts/windows-defaults.ps1`). Off by default; HKCU only, no\nadmin needed; some changes show after an Explorer restart.\n\n## Features\n\n- **Dual-shell support** — All scripts work in both bash and zsh (POSIX-compatible)\n- **Encrypted secrets** — Age-encrypted tokens and file secrets, auto-loaded at login\n- **AI integration** — Claude Code (primary) + OpenCode (secondary, Go subscription) + Gemini CLI with 21 custom skills, unified by `AGENTS.md` SSOT\n- **Cross-platform** — Symlinks on Linux, copies on Windows (no admin required); macOS planned\n- **Editor \u0026 shell ergonomics** — `.editorconfig` for cross-IDE consistency + `.inputrc` for case-insensitive tab-completion and arrow-key history search\n- **Tested** — 316 BATS tests + ShellCheck + PSScriptAnalyzer in CI\n\n## Structure\n\n```text\n├── setup-linux.sh              # Linux setup (symlinks); macOS planned\n├── setup-windows.ps1           # Windows setup (copies)\n├── cli/                        # `dotf` Go CLI (doctor, init, env, spec) — primary user-facing tool\n├── scripts/                    # Shell utilities (NOT on PATH — see Human entrypoints below)\n│   ├── utils.sh                # Shared function library (sourced by other scripts)\n│   ├── load-secrets.sh / .ps1  # Secrets → env vars (sourced at login)\n│   ├── vault.sh                # Vault tooling dispatcher\n│   └── …                       # ~50 scripts total (hooks, CI helpers, secret tools)\n├── sensitive/                  # Encrypted secrets\n│   └── *.secret.age            # Encrypted files (tracked)\n├── AGENTS.md                   # Cross-agent SSOT (canonical system prompt)\n├── ai/                         # Per-agent config overlays (thin pointers to AGENTS.md)\n│   ├── claude/CLAUDE.md        # Claude Code extensions (pointer to AGENTS.md)\n│   ├── agy/AGY.md              # Gemini/AGY extensions (pointer to AGENTS.md)\n│   ├── copilot/                # Copilot extensions (pointer to AGENTS.md)\n│   ├── opencode/opencode.jsonc # OpenCode config (providers + MCP)\n│   └── …                       # pi, hermes, nan\n├── harness/                    # Compiled AI-skill records (generated from the vault by compile-harness.sh)\n├── docs/                       # Docs-as-code: architecture.md, adr/, runbooks/, troubleshooting/, lessons.md\n├── specs/                      # Spec-Driven Development feature folders (+ archive/)\n├── git-hooks/                  # Global pre-commit/pre-push dispatcher (GUARD-001)\n├── systemd/                    # Linux self-update + hive timers/services\n├── windows/                    # Windows-specific assets (hive supervisor, upgrade)\n├── .github/                    # CI workflows (lint, test, spec-gate)\n├── ssh/                        # SSH config + public key\n├── powershell/profile.ps1      # Windows PowerShell profile\n├── tests/                      # BATS + Pester test suite\n└── .zsh/                       # Zsh modules (aliases, functions)\n```\n\n## Human entrypoints\n\nScripts in `scripts/` are **not on PATH**. They are invoked via shell aliases (defined in\n`.zsh/aliases.zsh` and `.bashrc`) or sourced at login. The table below lists the ~8\nscripts that a human ever runs directly — everything else is a library, hook, or CI helper.\n\n| Alias / command | Script | What it does |\n|---|---|---|\n| `./setup-linux.sh` | `setup-linux.sh` | Bootstrap Linux: install tools, deploy configs, register MCPs |\n| `.\\setup-windows.ps1` | `setup-windows.ps1` | Bootstrap Windows: same, via PowerShell |\n| `dotf doctor` | `dotf` CLI | Post-setup verification (versions, paths, symlinks, env vars, env-contract) |\n| `dotf init [path] --stack \u003cs\u003e` | `dotf` CLI | Scaffold a new fully-practiced repo (AGENTS.md + SDD, CI, pre-commit, git) |\n| `vault \u003csubcommand\u003e` | `scripts/vault.sh` | Vault tooling: `vault health`, `vault maintenance`, `vault check-escapes` |\n| `profile-shell` | `scripts/shell-profile.sh` | Measure shell startup time (zsh/bash, --detail for per-function) |\n| `obs` | `scripts/obs-cli.sh` | Open Obsidian vault (Linux, --no-sandbox, GUI check) |\n| `. scripts/load-secrets.sh` | `scripts/load-secrets.sh` | Decrypt age secrets → env vars (auto-sourced at login; manual when adding a new secret) |\n\n## Key Commands\n\n### Secrets\n\n```bash\nsecrets_add VAR_NAME filename       # Add new env var secret\nsecrets_add_file VAR FILE DEST      # Add file secret (kubeconfig, SSH keys)\nsecrets_rotate VAR_NAME             # Rotate existing secret\nsecrets_show VAR_NAME               # Show value (memory/disk/.age fallback)\nsecrets_list                        # List all secrets and status\nsecrets_check                       # Validate mapping integrity\n```\n\n### Machine-local overrides\n\nNon-sensitive, per-machine shell config (a host-only `PATH` prepend, a VM-only alias) goes in `~/.zshrc.local` / `~/.bashrc.local` — gitignored, sourced **last** so it can override anything above. Copy from the committed `.zshrc.local.example` / `.bashrc.local.example`.\n\n\u003e **`.local` is not for secrets.** API keys, tokens and credentials always go through the age system above (`sensitive/*.secret.age` + `secrets/registry.yaml`), never a `.local` file.\n\n### Cross-machine paths (ADR-025)\n\nStructural paths (vault, repo, agent homes) resolve through a cascade, so the **same repo works on every machine** without editing tracked files:\n\n```\nenv var  →  ~/.config/dotfiles/machine.json (per-machine override)  →  env-contract.json default[OS]\n```\n\n**To change where a path points:**\n\n| You want to… | Edit | Then |\n|---|---|---|\n| Relocate something on **this machine** (e.g. the vault moved) | `~/.config/dotfiles/machine.json` | `dotf env generate` → open a new shell |\n| Change the **default for all machines** | `env-contract.json` (the `default` block) | commit → on each machine `dotf env generate` (or re-run setup) |\n\n`dotf env generate` renders `~/.dotfiles/paths.{sh,ps1}` (sourced by your shell profile); **never edit those — they carry a `DO NOT EDIT` header.** Verify with `dotf doctor` (asserts no drift) or `dotf env path VAULT_PATH` (prints the resolved value). `machine.json` is gitignored and holds **only** the keys this machine overrides — copy `machine.json.example` to start. Full rationale: [`docs/adr/adr-025-cross-machine-path-resolution.md`](docs/adr/adr-025-cross-machine-path-resolution.md).\n\n### AI Tools\n\n```bash\ndotf init my-project --stack python  # Scaffold a new fully-practiced repo\nclaude                               # Start Claude Code session\n\u003e /audit src/auth.py                 # Use skills via slash commands\ngpr audit \"$(cat src/main.py)\"      # Gemini saved-prompt helper (~/.gemini/prompts/audit.md)\noc                                   # OpenCode TUI (Go subscription, DeepSeek V4 Pro default)\nqq por que tardas tanto?             # one-shot question (no quotes needed in zsh) -\u003e qwen3.6-plus (ES-friendly)\nqf explain the C10k problem         # one-shot question -\u003e deepseek-v4-flash (faster, technical)\n```\n\n**AI skills** are edited in the vault (`00_meta/skills/\u003cname\u003e/`), compiled to committed\nrecords under `harness/skills/`, and deployed per-agent by `scripts/compile-harness.sh`\n(Claude, OpenCode, Gemini/AGY, Copilot). Do not add skill directories to the repo — edit\nin the vault and re-run setup. Pipeline details: the vault's `pattern-cross-agent-skill-pipeline.md`.\n\n### Sync\n\n```bash\ndotfiles-sync                       # Bidirectional sync + git push/pull\ndotfiles-sync --secrets-only        # Only sync sensitive/ files\n```\n\n### Diagnostics\n\n```bash\ndotf doctor                         # Healthcheck: versions, paths, symlinks, env vars (`hc` on Windows)\ndch                                 # Drift check: repo vs ~/.dotfiles deploy dir\nprofile-shell                       # Measure shell startup time (zsh default)\nprofile-shell --shell bash --detail # Per-function breakdown via zprof/xtrace\nvault help                          # Vault tooling dispatcher (health / maintenance / check-escapes)\n```\n\n### Shell helpers\n\nPortable swiss-army functions in `.zsh/functions.sh`, sourced by **both** bash and\nzsh (curated from [mathiasbynens/dotfiles](https://github.com/mathiasbynens/dotfiles)):\n\n```bash\nmkd \u003cdir\u003e            # mkdir -p \u003cdir\u003e \u0026\u0026 cd into it\ngz \u003cfile\u003e            # show original vs gzipped size + ratio (read-only)\ndataurl \u003cfile\u003e       # print a base64 data: URI (MIME auto-detected)\ntargz \u003cfile|dir\u003e     # create \u003cinput\u003e.tar.gz (zopfli \u003e pigz \u003e gzip by availability)\nserver [port]        # serve the current dir over HTTP (default 8000) + open browser\ngetcertnames host[:port]  # print a TLS cert's Common Name + Subject Alt Names\n```\n\nThe names `mkd`, `gz`, `server` are short and may shadow a binary on `$PATH`. If one\nconflicts, re-alias it in `~/.zshrc.local` / `~/.bashrc.local` (see *Machine-local\noverrides*).\n\n### tmux\n\nTwo use cases this setup is tuned for: **(1) split-pane multiplexing** (editor + AI agent + tests side by side) and **(2) session persistence** (close the laptop / drop SSH and come back to the same state).\n\n```bash\n# --- The 6 commands you actually need ---\n\ntx dotfiles                # Start (or re-attach) a session named \"dotfiles\"\n                           # Inside tmux now: prompt shows [dotfiles]\n\n# Split for editor + AI + tests:\n#   C-b %                  Split vertically  (editor | agent)\n#   C-b \"                  Split horizontally (... above tests)\n#   C-b h/j/k/l            Move between panes (vim-style)\n#   C-b z                  Zoom current pane fullscreen (toggle)\n\n# Pause / resume:\n#   C-b d                  Detach — session keeps running in background\ntx dotfiles                # Re-attach later (same command). Layout preserved.\n\n# --- The rest (use occasionally) ---\n\ntxl                        # List all sessions\ntxa                        # Attach to most recent (no name needed)\ntxk \u003cname\u003e                 # Kill a named session\nsshmux \u003chost\u003e [session]    # SSH + attach-or-create remote tmux (survives drops)\n\n# Inside tmux:\n#   C-b r                  Reload ~/.tmux.conf after editing\n#   C-b x                  Close current pane\n#   C-b [                  Scroll mode (q to exit, / to search)\n```\n\nFull reference and pane-layout recipes: [`docs/runbooks/guide-tmux.md`](docs/runbooks/guide-tmux.md).\n\n## Requirements\n\n**Linux:** git, bash/zsh, tmux (`sudo apt install tmux`)\n\n**Windows:** git, PowerShell\n\n**macOS:** planned — not yet supported (no `setup-macos.sh`)\n\n**Recommended:** age, gh (GitHub CLI), direnv, zoxide, eza\n\n## Contributing\n\nPRs ≥50 LOC of production diff must include an active `specs/\u003cfeature-id\u003e/` folder (Spec-Driven Development). The `spec-gate` CI check enforces this; failures link back to `AGENTS.md` \"Discipline Gate\". Escape hatch: add the `skip-sdd` label AND a non-empty `## SDD skip rationale` section in the PR body. Optional local pre-push hook: `./scripts/install-precommit.sh --with-sdd-gate`.\n\n## Documentation\n\nProject-bound knowledge lives in [`docs/`](docs/) (docs-as-code):\n\n- [`docs/architecture.md`](docs/architecture.md) — **where does X live**: the normative repo tree, the `dotf` CLI layout, and the language boundary pointers (drift-guarded by CI)\n- [`docs/adr/`](docs/adr/) — Architecture Decision Records (age encryption, dual-shell, BATS testing, two-directory sync, symlinks vs copies, multi-agent runtime, model-tier policy, …) plus the repo audits and architecture map\n- [`docs/runbooks/`](docs/runbooks/) — operational procedures (secrets management, AI tools setup, tool installation, tmux, OpenCode, self-deploy timer)\n- [`docs/troubleshooting/`](docs/troubleshooting/) — known issues and their fixes (secrets, AI tools, Hive MCP, claude-mem)\n- [`docs/lessons.md`](docs/lessons.md) — accumulated gotchas and post-mortems\n\nStrategic context, roadmap, and session memory live in the maintainer's cross-project knowledge store and are intentionally not committed here.\n\n## Related Projects\n\n- [Boilerplates](https://github.com/mlorentedev/boilerplates) — Project templates\n- [Cheatsheets](https://github.com/mlorentedev/cheat-sheets) — Quick references\n\n## License\n\n[MIT License](LICENSE) — Free to use and modify with attribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fdotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlorentedev%2Fdotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fdotfiles/lists"}