fix(qenv): Improve documentation, update dependencies, and refine project configuration

.serena/memories/code_style_conventions.md

@@ -0,0 +1,38 @@
+# Code Style and Conventions
+
+## TypeScript Conventions
+- Use TypeScript with ES modules (type: "module" in package.json)
+- All files use `.js` extensions in imports (even for .ts files)
+- Interfaces prefixed with `I` (e.g., `IUserData`)
+- Types prefixed with `T` (e.g., `TEnvVarRef`)
+- Filenames must be lowercase
+- Avoid ENUMs when possible
+
+## File Organization
+- Source code in `ts/` directory
+- Tests in `test/` directory
+- Plugin imports in `ts/qenv.plugins.ts`
+- Main exports in `ts/index.ts`
+- Class files named as `qenv.classes.<classname>.ts`
+
+## Import Style
+- Import all dependencies in plugins file
+- Reference as `plugins.moduleName.method()`
+- Use full import paths with .js extension
+- Group imports: external packages, then internal modules
+
+## Testing
+- Use @git.zone/tstest framework
+- Import expect from tapbundle: `import { tap, expect } from '@git.zone/tstest/tapbundle'`
+- Test files end with `export default tap.start()` (tstest pattern)
+- Test file naming: `*.both.ts`, `*.node.ts`, or `*.browser.ts`
+
+## Documentation
+- Keep comments minimal unless specifically requested
+- README should be lowercase: `readme.md`
+- Documentation should be engaging and use emojis where appropriate
+
+## Git Conventions
+- Small, focused commits
+- Use `git mv` for file operations
+- Never commit without running tests and type checks

.serena/memories/project_overview.md

@@ -0,0 +1,37 @@
+# Qenv Project Overview
+
+## Purpose
+@push.rocks/qenv is a TypeScript/Node.js module for managing environment variables in Node.js projects. It provides a unified interface for loading environment variables from multiple sources:
+- Process environment variables
+- YAML configuration files (.yml/.yaml)
+- JSON configuration files (.json)
+- Docker secrets
+- Dynamic/async variable resolution via functions
+
+## Key Features
+- Support for required and optional environment variables
+- Multi-source loading hierarchy (env vars > config files > Docker secrets)
+- Base64-encoded object support for complex configurations
+- Synchronous and asynchronous variable retrieval
+- Strict mode with error throwing for unset variables
+- TypeScript with full type definitions
+- Logging via @push.rocks/smartlog
+
+## Main Components
+- `Qenv` class: Core class for environment variable management
+- `CloudlyAdapter`: Configuration vault integration
+- Support for `qenv.yml` (required vars definition) and `env.yml`/`env.json` (values)
+
+## Tech Stack
+- TypeScript
+- Node.js
+- pnpm package manager
+- @push.rocks ecosystem libraries (smartfile, smartlog, smartpath)
+- @git.zone tools for building and testing
+
+## Dependencies
+- @api.global/typedrequest
+- @configvault.io/interfaces  
+- @push.rocks/smartfile
+- @push.rocks/smartlog
+- @push.rocks/smartpath

.serena/memories/suggested_commands.md

@@ -0,0 +1,30 @@
+# Suggested Commands for Qenv Development
+
+## Build & Test Commands
+- `pnpm test` - Run tests with tstest
+- `pnpm build` - Build the project with tsbuild (includes --web --allowimplicitany flags)
+- `pnpm buildDocs` - Generate documentation with tsdoc
+
+## Development Tools
+- `tsx <file>` - Execute TypeScript files directly (globally available)
+- `tstest test/test.some.ts --verbose` - Run specific test file with verbose output
+
+## Package Management
+- `pnpm install` - Install dependencies
+- `pnpm install --save-dev <package>` - Add development dependency
+- `pnpm install <package>` - Add production dependency
+
+## Git Operations
+- `git mv <old> <new>` - Move/rename files preserving history
+- `git status` - Check current repository status
+- `git diff` - View uncommitted changes
+
+## Type Checking
+- `tsbuild check test/**/* --skiplibcheck` - Type check test files
+- `pnpm run build` - Type check and build module files
+
+## System Commands (Linux)
+- `ls` - List files
+- `find . -name "pattern"` - Find files by pattern
+- `rg "pattern"` - Search file contents (ripgrep)
+- `curl` - Make HTTP requests for testing/debugging

.serena/memories/task_completion_checklist.md

@@ -0,0 +1,32 @@
+# Task Completion Checklist
+
+When completing any development task in the qenv project, follow these steps:
+
+## Pre-Commit Checks
+1. **Run Tests**: `pnpm test`
+   - Ensure all tests pass
+   - Add new tests for new functionality
+
+2. **Type Checking**: `pnpm run build`
+   - Verify no TypeScript errors
+   - Check that build output is generated correctly
+
+3. **Code Quality**:
+   - Verify code follows project conventions
+   - Ensure no console.log statements left in production code
+   - Check imports use proper .js extensions
+
+## Documentation Updates
+- Update README.md if API changes
+- Update changelog.md for notable changes
+- Ensure JSDoc comments for public APIs
+
+## Final Verification
+- Review changes with `git diff`
+- Test the module can be imported correctly
+- Verify no breaking changes to public API
+
+## Important Notes
+- NEVER commit without explicit user approval
+- Always run tests and build before suggesting commit
+- If lint/typecheck commands unknown, ask user and update CLAUDE.md

.serena/project.yml

@@ -0,0 +1,68 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: typescript
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed)on 2025-04-07
+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. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# 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: ""
+
+project_name: "qenv"