From a150408a5ace608669f3c568d31ca55f197141b7 Mon Sep 17 00:00:00 2001 From: Alexander Miroshnichenko Date: Wed, 23 Sep 2026 14:54:50 +0300 Subject: [PATCH] Add Serena configuration and project memories (Set up Serena IDE integration with a Nix language server and create a memory graph documenting package conventions, core structure, tech stack, and task completion workflows.) --- .serena/.gitignore | 2 + .serena/memories/conventions.md | 23 ++++ .serena/memories/core.md | 30 +++++ .serena/memories/memory_maintenance.md | 33 +++++ .serena/memories/suggested_commands.md | 34 +++++ .serena/memories/task_completion.md | 11 ++ .serena/memories/tech_stack.md | 11 ++ .serena/project.yml | 169 +++++++++++++++++++++++++ 8 files changed, 313 insertions(+) create mode 100644 .serena/.gitignore create mode 100644 .serena/memories/conventions.md create mode 100644 .serena/memories/core.md create mode 100644 .serena/memories/memory_maintenance.md create mode 100644 .serena/memories/suggested_commands.md create mode 100644 .serena/memories/task_completion.md create mode 100644 .serena/memories/tech_stack.md create mode 100644 .serena/project.yml diff --git a/.serena/.gitignore b/.serena/.gitignore new file mode 100644 index 0000000..2e510af --- /dev/null +++ b/.serena/.gitignore @@ -0,0 +1,2 @@ +/cache +/project.local.yml diff --git a/.serena/memories/conventions.md b/.serena/memories/conventions.md new file mode 100644 index 0000000..ae8e493 --- /dev/null +++ b/.serena/memories/conventions.md @@ -0,0 +1,23 @@ +# nix-overlay — package conventions + +## Directory pattern (every package) +`packages//default.nix` (wrapper, receives blueprint args) + `packages//package.nix` (the derivation, `pkgs.callPackage`-style argsets). + +Wrapper variants: +- Plain: `{ pkgs, ... }: pkgs.callPackage ./package.nix { }` +- Needs blueprint extras: pass `perSystem`, `inputs`, etc. through explicitly. +- Alternate nixpkgs (freetoken): wrapper ignores `pkgs` for the derivation and calls `inputs.nixpkgs-torch211.legacyPackages.${pkgs.stdenv.hostPlatform.system}.callPackage ./package.nix { }`. + +## Derivedivation requirements +- Use `stdenv.mkDerivation rec { pname; version; }` or `rustPlatform.buildRustPackage` (Rust: `cargoHash`; Go/Python equivalents as needed). +- `meta.description` required (feeds the default meta-package listing). +- `meta.mainProgram` set for CLI-providing packages. +- Organizational attrs via `passthru`: `category` (e.g. "AI Coding Agents"), `hideFromDocs = true` to exclude from docs listing. +- No `with pkgs;` at top level of Nix files (scope issues). +- No hardcoded system paths/system assumptions. + +## Adding a package (sequence) +mkdir → package.nix → default.nix wrapper → `git add packages//` (required for blueprint discovery) → `nix build .#` → update README Available Packages table → commit (conventional-commit format). + +## Naming +- Package dir name = flake output attr name (kebab-case). diff --git a/.serena/memories/core.md b/.serena/memories/core.md new file mode 100644 index 0000000..5bde399 --- /dev/null +++ b/.serena/memories/core.md @@ -0,0 +1,30 @@ +# nix-overlay — core + +Nix flake overlay (numtide/blueprint-based) exposing extra packages for Nix/NixOS. +Repo: `git+https://git.millerson.name/alex/millerson-overlay.nix.git` + +## Source map +- `flake.nix` — inputs + outputs; blueprint drives perSystem outputs; overlays/modules added manually on top. +- `overlays/default.nix` — binary-cache-friendly: maps blueprint's pre-built `packages` under namespace `millerson-nix-overlay`. +- `overlays/shared-nixpkgs.nix` — builds `packages/` tree against consumer's `final` via `mkPackagesFor`; shares deps, cache only hits on matching nixpkgs rev. +- `packages//default.nix` + `package.nix` — every package follows this wrapper/derivation split. See `mem:conventions` for patterns. +- `packages/default/` — meta-package; generates name\tdesc list from `perSystem.self`, filtering `passthru.hideFromDocs`. +- `packages/flake-inputs/` — dummy derivation referencing all flake inputs so they get cached. `hideFromDocs = true`. +- `treefmt.toml` — nixfmt for `*.nix`, flake.lock excluded. +- `AGENTS.md` / `CLAUDE.md` — agent workflow rules (beads tracking, mandatory skills, caveman comms). + +## Project-wide invariants +- All overlay packages live under the single attrset `millerson-nix-overlay` (not top-level attrs). +- Blueprint discovers packages from the **git index**, not the working dir: new `packages//` must be `git add`-ed before `nix build .#` sees it. +- Three nixpkgs inputs; some packages deliberately build against non-default ones. See pins in `mem:tech_stack`. +- Everything under `packages/` uses `pkgs.callPackage ./package.nix { }` wrapper pattern; `default.nix` receives blueprint args (pkgs, perSystem, inputs, ...). + +## Task workflow (from AGENTS.md, enforced) +Runnable commands (build/format/update/bd/push): `mem:suggested_commands`. Exact done-checklist: `mem:task_completion`. + + +- ALL task tracking via `bd` (beads): `bd ready`, `bd update --claim`, `bd close `. NEVER TodoWrite/markdown TODOs. +- `bd prime` before starting work; `bd remember` for persistent knowledge (no MEMORY.md files). +- Session not complete until `git push` succeeds (`bd dolt push` skipping with "No remote is configured" is expected, not a failure). +- Commits use conventional-commit format. +- For nixpkgs/option lookups use the `nix` skill; for flake/devShell ops the `nix-flakes` skill; comms in caveman mode. diff --git a/.serena/memories/memory_maintenance.md b/.serena/memories/memory_maintenance.md new file mode 100644 index 0000000..6f84514 --- /dev/null +++ b/.serena/memories/memory_maintenance.md @@ -0,0 +1,33 @@ +# Memory Maintenance + +## Discovery Model + +- Core principle: progressive discovery through references, building a graph of memories. +- Initially, agents are provided with the list of all memories (names only). +- Agents should read `mem:core` as the top-level entry point (graph root). + This memory should contain references to other memories covering major project domains. + The referenced memories shall, in turn, shall contain references to even more specific memories, and so on. + The depth of the graph shall depend on the project complexity. +- Use topics/folders to group related memories in order to make the content structure explicit. + Folders can mirror project structure (e.g. modules like frontend/backend) or topics like debugging, architecture, etc. +- Memory references must use a mem: prefix inside backticks, e.g. `mem:frontend/core`. + The surrounding text should clearly indicate when to read the memory/which content to expect. + The text should provide more precise guidance than the memory name alone, + i.e. avoid a reference like "frontend debugging: `mem:frontend/debugging` and instead make clear which aspects of frontend debugging are covered. +- Memories themselves should not contain information about when to read them; this is the responsibility of the referring memory. + +## Style + +Dense agent notes, not prose docs. Prefer invariants, terse bullets. +Avoid obvious context, rationale, and examples unless they prevent likely mistakes. +Keep guidance durable and generalizable, not task-local. + +## Add/update threshold + +Add or update memories only with stable, non-obvious project conventions that avoid complex rediscovery in the future. +Do not add: quick-read facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon. + +## Maintenance Actions + +- Renaming memories: References are updated automatically if handled via Serena's memory rename tool. +- Checking for stale memories (e.g. after deletion): Call `serena memories check` for a report. \ No newline at end of file diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md new file mode 100644 index 0000000..2d8d897 --- /dev/null +++ b/.serena/memories/suggested_commands.md @@ -0,0 +1,34 @@ +# nix-overlay — commands + +All run from repo root (`nix-overlay/`). + +## Build / run +- `nix build .#` — build one package (must be `git add`-ed first if new; blueprint reads git index). +- `nix run .#` — run a package CLI (needs `meta.mainProgram`). +- `nix build .#default` — build the meta-package (package listing). +- `nix flake show` — inspect flake outputs (also index-limited). +- `nix flake check` — full check incl. formatting. +- `nix develop` — dev shell from blueprint. + +## Format +- `nix fmt` (treefmt → nixfmt on *.nix). Same as `nix flake check`'s format gate. + +## Package updates +- `nix-update ` — bump version + hashes (cargoHash etc.). +- `nix-update --version ` — specific version. +- `nix-update skillsmcp --version=branch=main` — for commit-pinned pkgs; or `--commit `. + +## Beads (mandatory task tracking) +- `bd prime` — session context, run before any work. +- `bd ready` / `bd show ` / `bd update --claim` / `bd close `. +- `bd remember` — persistent knowledge instead of MEMORY.md. +- `bd dolt push` — prints "No remote is configured — skipping." (expected; exit 0). + +## Session completion push +``` +git pull --rebase && bd dolt push && git push +git status # must show "up to date with origin" +``` + +## Serena +- `serena memories check` — verify memory references after edits/deletes. diff --git a/.serena/memories/task_completion.md b/.serena/memories/task_completion.md new file mode 100644 index 0000000..5fb13ed --- /dev/null +++ b/.serena/memories/task_completion.md @@ -0,0 +1,11 @@ +# nix-overlay — task completion + +Done when ALL of these pass/hold: + +1. Build passes: `nix build .#` (or `nix flake check` for cross-cutting changes). Never leave a package committed that doesn't build. +2. Formatting: `nix fmt` clean (nixfmt; `flake.lock` excluded). +3. New package is staged (`git add packages//`) before build — blueprint index requirement. +4. README.md Available Packages table updated if package added/changed visibly. +5. Commit: conventional commit format (use conventional-commit / caveman-commit skill). No work left uncommitted. +6. Beads: work claimed via `bd update --claim` before, `bd close ` after. +7. Pushed: `git pull --rebase && bd dolt push && git push` then `git status` shows "up to date with origin". `bd dolt push` skip message is expected, not a failure. Do not stop before push succeeds. diff --git a/.serena/memories/tech_stack.md b/.serena/memories/tech_stack.md new file mode 100644 index 0000000..ddff485 --- /dev/null +++ b/.serena/memories/tech_stack.md @@ -0,0 +1,11 @@ +# nix-overlay — tech stack + +- Language: Nix. Build system: Nix flake via `numtide/blueprint` (with `flake-parts`, `systems` for multi-system). +- Formatting: `treefmt-nix` → `nixfmt` on `*.nix` (`flake.lock` excluded in `treefmt.toml`). +- Multi-input nixpkgs setup (flake.nix) — pins matter, do not "unify" them: + - `nixpkgs` = nixos-unstable (default; blueprint follows it). + - `nixpkgs-latest` = nixos-unstable — needed by packages requiring newer toolchains: rustc >= 1.95 (mcp-gateway >= 3.4.0), go >= 1.26.3 (kubernetes-mcp-server >= 0.0.66). + - `nixpkgs-torch211` = pinned rev `549bd84d6279f9852cae6225e372cc67fb91a4c1` — freetoken pins torch>=2.11,<2.12 / triton==3.6.0; nixos-unstable ships torch 2.13/triton 3.7, so freetoken builds via `inputs.nixpkgs-torch211.legacyPackages.${system}.callPackage` (see `packages/freetoken/default.nix`). + - `bun2nix` pinned to branch `staging-2.1.0` until catalog support (bun2nix#86) lands on default branch (TODO #4001). +- Package kinds in `packages/`: mostly Rust (rustPlatform.buildRustPackage), Go, Python/torch, Node/bun; each self-contained in its own dir. +- `flake.lock` managed only via `nix flake update` — never hand-edited. diff --git a/.serena/project.yml b/.serena/project.yml new file mode 100644 index 0000000..f9215fd --- /dev/null +++ b/.serena/project.yml @@ -0,0 +1,169 @@ +# the name by which the project can be referenced within Serena/when chatting with the LLM. +project_name: "nix-overlay" + +# list of language servers to start when using the LSP backend; choose from: +# ada al angular ansible bash +# bsl clojure cpp cpp_ccls crystal +# csharp csharp_omnisharp cue dart deno +# elixir elm erlang fortran fsharp +# gdscript gleam go groovy haskell +# haxe hlsl html java json +# julia kotlin latex lean4 lua +# luau markdown matlab msl nextflow +# nix ocaml pascal perl php +# php_phpactor php_phpantom powershell python python_basedpyright +# python_jedi python_pyrefly python_ty qml r +# rego ruby ruby_solargraph rust scala +# scss solidity svelte swift systemverilog +# terraform toml typescript typescript_vts vue +# wolfram yaml zig +# (This list may be outdated; generated with scripts/print_language_list.py; +# For the current list, see values of the LanguageServerId enum here: +# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py) +# For some languages, there are several alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.) +# Note: +# - For C, use cpp +# - For JavaScript, use typescript +# - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root) +# - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm) +# - For Deno projects, use deno (serves the same .ts/.js files as typescript; requires the deno CLI on PATH) +# - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three) +# - For Free Pascal/Lazarus, use pascal +# Special requirements: +# Some language servers require additional setup/installations. +# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers +# When using multiple language servers, the first language server that supports a given file will be used for that file. +# The first language server is the default language and the respective language server will be used as a fallback. +# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored. +language_servers: +- nix + +# the encoding used by text files in the project +# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings +encoding: "utf-8" + +# optional shell command to run before the language backend (LSP or JetBrains) is initialised. +# the command runs in the project root directory and is only executed if the project is trusted +# (see trusted_project_path_patterns in the global configuration). +# serena waits for the command to exit: a non-zero exit code is logged as an error but does not +# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety +# backstop for non-terminating commands; on expiry the process is killed and activation continues. +# example: activation_command: "npx nx run-many -t build" +activation_command: + +# maximum time in seconds to wait for activation_command to complete before killing it (default 180s). +# must be a positive number. +activation_command_timeout: 180.0 + +# line ending convention to use when writing source files. +# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default) +# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings. +line_ending: + +# The language backend to use for this project. +# If not set, the global setting from serena_config.yml is used. +# Valid values: LSP, JetBrains +# Note: the backend is fixed at startup. If a project with a different backend +# is activated post-init, an error will be returned. +language_backend: + +# whether to use project's .gitignore files to ignore files +ignore_all_files_in_gitignore: true + +# advanced configuration option allowing to configure language server-specific options. +# Maps the language key to the options. +# The settings are considered only if the project is trusted (see global configuration to define trusted projects). +# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings +ls_specific_settings: {} + +# list of workspace folder paths (LSP backend only). +# These folders will be used to build up Serena's symbol index. +# Paths must be within the project root and should thus be relative to the project root. +# Furthermore, the paths should not be filtered by ignore settings. +# Default setting: The entire project root folder (".") is considered. +# In (large) monorepos, this can be used to index only subfolders of the project root, e.g. +# ls_workspace_folders: +# - "./subproject1" +# - "./subproject2" +ls_workspace_folders: +- "." + +# list of additional workspace folder paths for cross-package reference support. +# Paths can be absolute or relative to the project root. +# Each folder is registered as an LSP workspace folder, enabling language servers to discover +# symbols and references across package boundaries, but these folders are not indexed by Serena, +# i.e. the respective symbols will not be found using Serena's symbol search tools. +# Example: +# additional_workspace_folders: +# - ../sibling-package +# - ../shared-lib +ls_additional_workspace_folders: [] + +# list of additional paths to ignore in this project. +# Same syntax as gitignore, so you can use * and **. +# Important: quote patterns that start with `*`, otherwise YAML treats them as aliases. +# Example: +# ignored_paths: +# - "examples/**" +# - ".worktrees/**" +# - "**/bin/**" +# - "**/obj/**" +# Note: global ignored_paths from serena_config.yml are also applied additively. +ignored_paths: [] + +# whether the project is in read-only mode +# If set to true, all editing tools will be disabled and attempts to use them will result in an error +# Added on 2025-04-18 +read_only: false + +# list of tool names to exclude. +# This extends the existing exclusions (e.g. from the global configuration) +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html +excluded_tools: [] + +# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default). +# This extends the existing inclusions (e.g. from the global configuration). +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html +included_optional_tools: [] + +# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools. +# This cannot be combined with non-empty excluded_tools or included_optional_tools. +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html +fixed_tools: [] + +# list of mode names that are to be activated by default, overriding the setting in the global configuration. +# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. +# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply. +# Otherwise, this overrides the setting from the global configuration (serena_config.yml). +# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply +# for this project. +# This setting can, in turn, be overridden by CLI parameters (--mode). +# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes +default_modes: + +# list of mode names to be activated additionally for this project, e.g. ["query-projects"] +# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. +# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes +added_modes: + +# initial prompt for the project. It will always be given to the LLM upon activating the project +# (contrary to the memories, which are loaded on demand). +initial_prompt: "" + +# time budget (seconds) per tool call for the retrieval of additional symbol information +# such as docstrings or parameter information. +# This overrides the corresponding setting in the global configuration; see the documentation there. +# If null or missing, use the setting from the global configuration. +symbol_info_budget: + +# list of regex patterns which, when matched, mark a memory entry as read‑only. +# Extends the list from the global configuration, merging the two lists. +read_only_memory_patterns: [] + +# list of regex patterns for memories to completely ignore. +# Matching memories will not appear in list_memories or activate_project output +# and cannot be accessed via read_memory or write_memory. +# To access ignored memory files, use the read_file tool on the raw file path. +# Extends the list from the global configuration, merging the two lists. +# Example: ["_archive/.*", "_episodes/.*"] +ignored_memory_patterns: []