fix(docs): refine language and formatting in architecture, async design, development, exec security, and worker implementation documents

Author: mceachen

doc/internal/architecture.md

@@ -160,4 +160,4 @@ The shim layer approach allows us to ship a standalone npm package that:
 - Maintains full API compatibility
 - Can track upstream improvements
 
-While this required significant effort to create the compatibility layer, it provides the best balance between compatibility, maintainability, and usability.
+The compatibility layer took real effort to build, but it keeps the package compatible, maintainable, and easy to use.

doc/internal/async-design.md

@@ -1,8 +1,8 @@
 # Async API Design Analysis for @photostructure/sqlite
 
-## Executive Summary
+## Summary
 
-This document analyzes options for adding asynchronous API support to the @photostructure/sqlite library, which currently provides a synchronous SQLite interface matching Node.js's built-in sqlite module. After careful analysis, we recommend creating a separate package for the async API rather than integrating it into the existing library.
+This document analyzes options for adding asynchronous API support to @photostructure/sqlite (currently sync-only, matching Node.js's built-in sqlite module). We recommend a separate package for the async API rather than integrating it into the existing library.
 
 ## Current State
 
@@ -291,7 +291,7 @@ const user = await stmt.get(userId);
 
 ## Conclusion
 
-Creating a separate async package is the recommended approach. It provides the clearest path forward, aligns with Node.js's design philosophy, and minimizes risk to existing users. The AsyncWorker pattern from node-addon-api provides a solid foundation for implementation.
+A separate async package is the recommended approach. It follows Node.js's own design philosophy and avoids any risk to existing sync users. The AsyncWorker pattern from node-addon-api is the right building block.
 
 ## Next Steps
 

doc/internal/development.md

@@ -2,50 +2,37 @@
 
 Information about the development of @photostructure/sqlite.
 
-## Project Timeline
+## Project overview
 
-This project demonstrates modern software development practices with AI assistance:
+- Full API compliance running in both ESM and CJS modes
+- Multi-platform CI/CD with dedicated ARM64 and x64 build jobs across all platforms
+- Security scanning and memory leak detection
+- Automated sync from Node.js and SQLite upstream
+- [Benchmarking suite](../../benchmark/README.md) covering popular Node.js SQLite libraries
 
-- **900+ lines of C++** - Core SQLite binding implementation
-- **17,000+ lines of TypeScript tests** - Comprehensive test coverage
-- **400+ tests** with full API compliance running in both ESM and CJS modes
-- **Multi-platform CI/CD** with dedicated ARM64 and x64 build jobs across all platforms
-- **Security scanning** and memory leak detection
-- **Automated sync** from Node.js and SQLite upstream
-- **Robust [benchmarking suite](../../benchmark/README.md)** including all popular Node.js SQLite libraries
-
-## AI-Assisted Development
+## AI-assisted development
 
 This project was built with substantial assistance from [Claude Code](https://claude.ai/referral/gM3vgw7pfA), an AI coding assistant.
 
-### Development Cost
-
-- **API usage**: ~$1400 in Claude API tokens
-- **Actual cost**: $200/month MAX 20x plan subscription
-- **Time saved**: At least a month of setup, analysis, porting and testing
+### Development process
 
-### Development Process
-
-1. **Initial Analysis**: Claude analyzed the Node.js SQLite source code and architecture
-2. **Shim Layer Design**: Developed compatibility layer for Node.js internals
+1. **Analysis**: Claude analyzed the Node.js SQLite source code and architecture
+2. **Shim layer**: Developed compatibility layer for Node.js internals
 3. **Implementation**: Ported C++ code with N-API adaptations
-4. **Testing**: Created comprehensive test suite with 400+ tests
+4. **Testing**: Created test suite
 5. **Documentation**: Generated user and API documentation
 6. **CI/CD**: Set up multi-platform build and release pipeline
 
-### Quality Assurance
+### Quality assurance
 
-While AI significantly accelerated development, all code underwent:
+All code was reviewed by a human and validated by automated tests before merging:
 
-- Human review before merging
-- Comprehensive automated testing
+- Automated testing across platforms
 - Memory leak detection (Valgrind, ASAN)
 - Security scanning (npm audit, OSV, CodeQL)
 - Performance benchmarking
 
-This approach demonstrates how AI-assisted development can accelerate complex system programming while maintaining high code quality through comprehensive testing and human oversight.
-
-## Building from Source
+## Building from source
 
 ### Prerequisites
 
@@ -56,7 +43,7 @@ This approach demonstrates how AI-assisted development can accelerate complex sy
   - **macOS**: Xcode Command Line Tools
   - **Windows**: Visual Studio 2019+
 
-### Build Commands
+### Build commands
 
 ```bash
 # Install dependencies
@@ -72,7 +59,7 @@ npm test
 npm run benchmark
 ```
 
-### Development Workflow
+### Development workflow
 
 ```bash
 # Watch mode for TypeScript
@@ -106,31 +93,31 @@ See [Architecture Documentation](./architecture.md) for details on:
 5. Ensure all tests pass
 6. Submit a pull request
 
-### Code Style
+### Code style
 
 - TypeScript/JavaScript: Prettier with project config
 - C++: clang-format with project style
 - Commit messages: Conventional Commits format
 
-### Testing Requirements
+### Testing requirements
 
 - New features must include tests
 - Tests must pass on all platforms
 - Memory leak tests for native code
 - Benchmark comparisons for performance changes
 
-## Release Process
+## Release process
 
 See [Release Process](./release-process.md) for detailed release instructions.
 
-## Upstream Synchronization
+## Upstream synchronization
 
 The project maintains synchronization with:
 
 - Node.js SQLite implementation
 - SQLite amalgamation source
 
-### GitHub API Authentication
+### GitHub API authentication
 
 To avoid rate limiting when syncing from GitHub (60 requests/hour for unauthenticated requests), set up authentication:
 
@@ -147,7 +134,7 @@ You can create a personal access token at: https://github.com/settings/tokens
 
 The token only needs public repository read access.
 
-### Sync Commands
+### Sync commands
 
 ```bash
 # Sync from Node.js

doc/internal/exec-security-comparison.md

@@ -40,7 +40,7 @@ process.env.NODE_ENV = "production"; // Controlled by app, not user
 execSync("NODE_ENV=production npm run build");
 ```
 
-### ⚠️ MISLEADING: "Safe" Looking But Still Dangerous
+### Misleading: "safe" looking but still dangerous
 
 ```javascript
 // Looks safe because of validation, but still risky
@@ -83,7 +83,7 @@ execFileSync(tool, ["--help"]); // User can run ANY executable!
 // Executes: /bin/rm --help (but what if args were different?)
 ```
 
-### ⚠️ FALSE SECURITY: Shell Features Still Available
+### False security: shell features still available
 
 ```javascript
 // Some programs interpret shell-like syntax themselves
@@ -94,7 +94,7 @@ execFileSync("eval", [userInput]); // If such a program existed
 
 ## Real-World Security Patterns
 
-### Pattern 1: Static Commands (Both Are Safe)
+### Pattern 1: static commands (both are safe)
 
 ```javascript
 // These are equally safe - no user input involved
@@ -105,7 +105,7 @@ execFileSync("docker", ["build", "-t", "myapp:latest", "."]);
 // The execFileSync version is more verbose with no security benefit here
 ```
 
-### Pattern 2: User Input as Arguments (execFileSync Wins)
+### Pattern 2: user input as arguments (execFileSync wins)
 
 ```javascript
 // DANGEROUS - shell interprets special characters
@@ -116,7 +116,7 @@ execSync(`grep "${searchTerm}" logfile.txt`);
 execFileSync("grep", [searchTerm, "logfile.txt"]);
 ```
 
-### Pattern 3: Complex Commands (execSync More Practical)
+### Pattern 3: complex commands (execSync more practical)
 
 ```javascript
 // Complex pipeline - execSync is cleaner
@@ -126,7 +126,7 @@ execSync('ps aux | grep node | grep -v grep | awk "{print $2}"');
 // Not more secure if the command is static!
 ```
 
-### Pattern 4: Running User Scripts (Both Dangerous)
+### Pattern 4: running user scripts (both dangerous)
 
 ```javascript
 // User uploads script.sh
@@ -140,9 +140,9 @@ execFileSync("bash", [uploadedScriptPath]);
 // The security issue is running untrusted code, not the exec method!
 ```
 
-## Security Best Practices
+## Security best practices
 
-### 1. Identify the Real Threat
+### 1. Identify the real threat
 
 ```javascript
 // Ask: "What part is user-controlled?"
@@ -157,7 +157,7 @@ execFileSync("git", ["checkout", userBranch]); // ✅ Safer
 execFileSync(userCommand, args); // ❌ Still dangerous
 ```
 
-### 2. Validate at the Right Level
+### 2. Validate at the right level
 
 ```javascript
 // ✅ GOOD: Whitelist allowed operations
@@ -171,7 +171,7 @@ const sanitized = userInput.replace(/[;&|`$]/g, ""); // Incomplete, error-prone
 execSync(sanitized); // Still dangerous!
 ```
 
-### 3. Use the Right Tool for the Job
+### 3. Use the right tool for the job
 
 ```javascript
 // For static commands, use what's clearer
@@ -197,17 +197,17 @@ execFileSync("tar", ["-czf", "archive.tgz", ...files]); // Safe argument passing
 
 ## Key Takeaways
 
-1. **execSync with static strings is perfectly safe** - The risk comes from interpolating user input, not the function itself.
+1. **execSync with static strings is perfectly safe.** The risk comes from interpolating user input, not the function itself.
 
-2. **execFileSync prevents shell interpretation** - But it doesn't prevent running malicious executables or scripts.
+2. **execFileSync prevents shell interpretation**, but it doesn't prevent running malicious executables or scripts.
 
 3. **The real security question** is "what does the user control?" not "which exec function am I using?"
 
-4. **Security theater is dangerous** - Blindly using execFileSync everywhere might hide real vulnerabilities while making code harder to maintain.
+4. **Security theater is dangerous.** Blindly using execFileSync everywhere might hide real vulnerabilities while making code harder to maintain.
 
-5. **Context matters** - A hardcoded `execSync('npm install')` is safer than `execFileSync(userPath, userArgs)`.
+5. **Context matters.** A hardcoded `execSync('npm install')` is safer than `execFileSync(userPath, userArgs)`.
 
-## Examples: Right Tool for the Job
+## Examples: right tool for the job
 
 ```javascript
 // ✅ Static command - execSync is fine and clearer