docs: rebuild KB in OKF v0.1 with live-verified facts
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
This commit is contained in:
Frank
@@ -0,0 +1,93 @@
|
||||
---
|
||||
type: reference
|
||||
title: Go
|
||||
description: Current best practices for Go projects - modules, project layout, HTTP frameworks, and tooling.
|
||||
tags:
|
||||
- go
|
||||
- golang
|
||||
- bootstrap
|
||||
- engineering
|
||||
timestamp: 2026-08-11
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
CUT
|
||||
# Go
|
||||
|
||||
This page covers current (2025/2026) best practices for Go projects.
|
||||
|
||||
## Bootstrap
|
||||
|
||||
Initialize a module:
|
||||
|
||||
```bash
|
||||
go mod init my-module
|
||||
```
|
||||
|
||||
Then write a `main.go` with `package main`.
|
||||
|
||||
## Project Layout
|
||||
|
||||
Follow the Standard Go Project Layout:
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── cmd/ # Application entrypoints
|
||||
├── internal/ # Private application code
|
||||
├── pkg/ # Public library code
|
||||
├── api/ # Protobuf or OpenAPI definitions
|
||||
├── deploy/ # Dockerfiles and Helm charts
|
||||
├── scripts/ # Build and CI scripts
|
||||
├── go.mod
|
||||
└── go.sum
|
||||
```
|
||||
|
||||
Use `internal/` for code that must stay private to the module.
|
||||
|
||||
## Tooling
|
||||
|
||||
| Category | Tool | Notes |
|
||||
|----------|------|-------|
|
||||
| Module manager | go modules | Built into the toolchain. |
|
||||
| Formatter | gofmt | Built in. |
|
||||
| Linter | golangci-lint | The standard CI aggregator. |
|
||||
| Testing | `go test ./...` | Use table-driven tests. |
|
||||
| Static analysis | staticcheck | Use with golangci-lint. |
|
||||
|
||||
## HTTP Frameworks
|
||||
|
||||
| Framework | Best For | Notes |
|
||||
|-----------|----------|-------|
|
||||
| Standard `net/http` | Most Go projects | Idiomatic, no dependencies. |
|
||||
| chi v5 | REST APIs | Minimalist, stdlib-compatible. |
|
||||
| gin | High-throughput APIs | Fast, JSON binding. |
|
||||
| echo | Full-featured APIs | Middleware and validation. |
|
||||
|
||||
Use the standard library or chi for most projects.
|
||||
|
||||
## Notable 2025/2026 Changes
|
||||
|
||||
* Go 1.24 added generic type aliases and `tool` directives in `go.mod`.
|
||||
* `go run` and `go build` cache executables and embed VCS metadata.
|
||||
* `go test -json` gives structured output for CI.
|
||||
|
||||
## Related Technologies
|
||||
|
||||
* pgx for PostgreSQL.
|
||||
* slog for structured logging.
|
||||
* cobra for command-line interfaces.
|
||||
* gRPC with `google.golang.org/grpc`.
|
||||
* testcontainers-go for integration tests.
|
||||
|
||||
## Citations
|
||||
|
||||
* [Go modules](https://go.dev/doc/modules)
|
||||
* [Go 1.24 release notes](https://go.dev/doc/go1.24)
|
||||
* [Standard Go Project Layout](https://github.com/golang-standards/project-layout)
|
||||
* [chi](https://github.com/go-chi/chi)
|
||||
|
||||
## See Also
|
||||
|
||||
* [SDLC and Tooling](../sdlc.md)
|
||||
* [Rust](rust.md)
|
||||
* [Docker and Podman](../infra/containers.md)
|
||||
@@ -0,0 +1,22 @@
|
||||
# Language and Framework Stacks
|
||||
|
||||
Current (2025/2026) bootstrap, tooling, and best practices for the major language ecosystems.
|
||||
|
||||
Each page covers one ecosystem. Use the page that matches the project language.
|
||||
|
||||
## Topics
|
||||
|
||||
* [Node.js and JavaScript](node-js.md) - Runtimes, package managers, TypeScript, tooling, monorepos.
|
||||
* [React](react.md) - Vite vs Next.js, component patterns, testing.
|
||||
* [Python](python.md) - uv, pyproject.toml, frameworks, linting, testing.
|
||||
* [Rust](rust.md) - cargo, editions, web frameworks, tooling.
|
||||
* [Go](go.md) - modules, project layout, HTTP frameworks, tooling.
|
||||
|
||||
## Cross-Ecosystem Patterns
|
||||
|
||||
* [SDLC and Tooling](../sdlc.md) - Git, CI/CD, testing, environments.
|
||||
* [Infrastructure and Cloud](../infra/index.md) - Containers and deployment.
|
||||
|
||||
## See Also
|
||||
|
||||
* [Engineering](../index.md) - The parent area.
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
type: reference
|
||||
title: Node.js and JavaScript
|
||||
description: Current bootstrap, tooling, and framework best practices for Node.js and JavaScript projects.
|
||||
tags:
|
||||
- node
|
||||
- javascript
|
||||
- typescript
|
||||
- bootstrap
|
||||
- engineering
|
||||
timestamp: 2026-08-11
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
CUT
|
||||
# Node.js and JavaScript
|
||||
|
||||
This page covers current (2025/2026) best practices for Node.js and JavaScript projects.
|
||||
|
||||
## Runtime and Package Manager
|
||||
|
||||
Use Node.js 22 LTS or Node.js 24 LTS. Use these versions for stability in production.
|
||||
|
||||
Choose a package manager by project type:
|
||||
|
||||
* npm for the default.
|
||||
* pnpm for monorepos.
|
||||
* Bun as an all-in-one runtime, package manager, test runner, and bundler.
|
||||
|
||||
## TypeScript
|
||||
|
||||
TypeScript is the default for new projects. Configure `strict: true` in `tsconfig.json`. Target `ES2022` or later. Use `module: ESNext` and `moduleResolution: bundler`.
|
||||
|
||||
## Bootstrap
|
||||
|
||||
Scaffold a Vite project with:
|
||||
|
||||
```bash
|
||||
npm create vite@latest my-app -- --template react-ts
|
||||
```
|
||||
|
||||
Scaffold a full-stack SSR app with Next.js:
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-app --yes
|
||||
```
|
||||
|
||||
## Tooling
|
||||
|
||||
| Category | Tool | Notes |
|
||||
|----------|------|-------|
|
||||
| Linter | ESLint 9 with flat config | Use `eslint.config.mjs`. |
|
||||
| Formatter | Prettier or Biome | Biome is faster and Prettier-compatible. |
|
||||
| Testing | Vitest or Jest | Vitest is the default for Vite projects. |
|
||||
| Bundler | Vite or Turbopack | Turbopack is the Next.js default. |
|
||||
|
||||
Use Biome if you want one fast tool for lint and format. Biome gained many lint rules from ESLint and TypeScript ESLint.
|
||||
|
||||
## Frameworks
|
||||
|
||||
* Express and Fastify for minimal servers.
|
||||
* NestJS for structured, opinionated applications.
|
||||
* Next.js for full-stack React with server-side rendering.
|
||||
|
||||
## Monorepos
|
||||
|
||||
Use Turborepo or Nx for JavaScript and TypeScript monorepos. Combine these tools with pnpm workspaces for dependency management.
|
||||
|
||||
## Related Technologies
|
||||
|
||||
* Remix, Nuxt, Astro, and SvelteKit as other meta-frameworks.
|
||||
* Deno as an alternative runtime.
|
||||
* esm.sh as a CDN for npm packages as ES modules.
|
||||
|
||||
## Citations
|
||||
|
||||
* [Node.js releases](https://nodejs.org/en/about/releases)
|
||||
* [Vite](https://vite.dev/)
|
||||
* [Biome](https://biomejs.dev/)
|
||||
* [Vitest](https://vitest.dev/)
|
||||
* [Bun](https://bun.com/)
|
||||
* [Next.js documentation](https://nextjs.org/docs)
|
||||
|
||||
## See Also
|
||||
|
||||
* [React](react.md)
|
||||
* [SDLC and Tooling](../sdlc.md)
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
type: reference
|
||||
title: Python
|
||||
description: Current best practices for Python projects - uv, pyproject.toml, frameworks, linting, and testing.
|
||||
tags:
|
||||
- python
|
||||
- uv
|
||||
- fastapi
|
||||
- django
|
||||
- bootstrap
|
||||
- engineering
|
||||
timestamp: 2026-08-11
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
CUT
|
||||
# Python
|
||||
|
||||
This page covers current (2025/2026) best practices for Python projects.
|
||||
|
||||
## Package and Project Management
|
||||
|
||||
Use `uv` for new projects. `uv` replaces pip, pip-tools, pyenv, poetry, and virtualenv. It is much faster than pip and supports workspaces and lockfiles.
|
||||
|
||||
Scaffold a project with:
|
||||
|
||||
```bash
|
||||
uv init my-project --bare
|
||||
```
|
||||
|
||||
The command creates a `pyproject.toml` and a virtual environment. A `uv.lock` file pins exact dependency versions. Do not edit the lockfile by hand.
|
||||
|
||||
Use `pyproject.toml` as the project manifest. It follows PEP 621. This replaces the older `setup.py`.
|
||||
|
||||
## Tooling
|
||||
|
||||
| Category | Tool | Notes |
|
||||
|----------|------|-------|
|
||||
| Linter and formatter | Ruff | Replaces Black, isort, flake8, and pylint. |
|
||||
| Type checker | pyright or mypy | Use pyright in VS Code. Use mypy for strict CI. |
|
||||
| Testing | pytest | Use pytest-asyncio for async tests. |
|
||||
| Pre-commit | pre-commit | Run ruff, mypy, and pytest. |
|
||||
|
||||
## Framework Comparison
|
||||
|
||||
| Framework | Best For | Notes |
|
||||
|-----------|----------|-------|
|
||||
| FastAPI | Modern REST APIs, async | Auto documentation, type-hint validation. |
|
||||
| Django | Full-stack web apps | Batteries included: ORM, admin, auth. |
|
||||
| Flask | Lightweight apps | Simpler than FastAPI. |
|
||||
|
||||
Use FastAPI for new REST APIs. The recommended workflow is `uv run fastapi dev`.
|
||||
|
||||
## Notable 2025/2026 Changes
|
||||
|
||||
* `uv` is the dominant project manager.
|
||||
* `ruff` replaced most separate lint and format tools.
|
||||
* `pyproject.toml` is the universal manifest.
|
||||
* Python 3.12 gives stability. Python 3.13 adds performance improvements.
|
||||
|
||||
## Related Technologies
|
||||
|
||||
* Uvicorn as the ASGI server.
|
||||
* SQLAlchemy 2.0 with Alembic for the ORM and migrations.
|
||||
* httpx for async HTTP clients.
|
||||
* pydantic-settings for configuration.
|
||||
* OpenTelemetry for observability.
|
||||
|
||||
## Citations
|
||||
|
||||
* [uv documentation](https://docs.astral.sh/uv/)
|
||||
* [Ruff](https://ruff.rs/)
|
||||
* [FastAPI](https://fastapi.tiangolo.com/)
|
||||
* [pyproject-build](https://pyproject-build.github.io/)
|
||||
|
||||
## See Also
|
||||
|
||||
* [SDLC and Tooling](../sdlc.md)
|
||||
* [Infrastructure and Cloud](../infra/index.md)
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
type: reference
|
||||
title: React
|
||||
description: Current best practices for React - Vite vs Next.js, component patterns, and testing.
|
||||
tags:
|
||||
- react
|
||||
- nextjs
|
||||
- frontend
|
||||
- bootstrap
|
||||
- engineering
|
||||
timestamp: 2026-08-11
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
CUT
|
||||
# React
|
||||
|
||||
This page covers current (2025/2026) best practices for React projects.
|
||||
|
||||
## Framework Choice
|
||||
|
||||
Create React App is deprecated. Use Vite or Next.js for new projects.
|
||||
|
||||
* Use Vite + React for a single-page application with a separate API.
|
||||
* Use Next.js for a full-stack application with server-side rendering.
|
||||
|
||||
Next.js uses the App Router with React Server Components by default. Components render on the server unless you mark them with `"use client"`.
|
||||
|
||||
## Bootstrap
|
||||
|
||||
Scaffold a Vite project:
|
||||
|
||||
```bash
|
||||
npm create vite@latest my-app -- --template react-ts
|
||||
```
|
||||
|
||||
Scaffold a Next.js project:
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-app --yes
|
||||
```
|
||||
|
||||
## Tooling
|
||||
|
||||
| Category | Tool | Notes |
|
||||
|----------|------|-------|
|
||||
| CSS | Tailwind CSS | Default in create-next-app. |
|
||||
| State | Zustand and TanStack Query | Zustand for client state. TanStack Query for server state. |
|
||||
| Testing | Vitest and Testing Library | Unit and integration tests. |
|
||||
| End-to-end | Playwright or Cypress | For user journeys. |
|
||||
| Lint and format | Biome or ESLint | Use Biome for one fast tool. |
|
||||
|
||||
## Component Patterns
|
||||
|
||||
* Keep components, hooks, and types near the routes that use them.
|
||||
* Use route groups for organization without changing the URL.
|
||||
* Use `_components` for code that must not become a route.
|
||||
* Use React Server Components to reduce client-side state.
|
||||
|
||||
## Notable 2025/2026 Changes
|
||||
|
||||
* React 19 is stable with Actions and new hooks.
|
||||
* Next.js 16 uses Turbopack as the default bundler.
|
||||
* Next.js no longer runs the linter as part of `next build`.
|
||||
|
||||
## Related Technologies
|
||||
|
||||
* Remix, Redwood, Gatsby, and Astro as other meta-frameworks.
|
||||
* Playwright for end-to-end testing.
|
||||
* Vercel Edge Functions and Cloudflare Workers for serverless.
|
||||
|
||||
## Citations
|
||||
|
||||
* [React](https://react.dev/)
|
||||
* [Next.js project structure](https://nextjs.org/docs/app/getting-started/project-structure)
|
||||
* [Biome](https://biomejs.dev/)
|
||||
* [Vitest](https://vitest.dev/)
|
||||
|
||||
## See Also
|
||||
|
||||
* [Node.js and JavaScript](node-js.md)
|
||||
* [Agent Instruction Files](../agents-files.md)
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
type: reference
|
||||
title: Rust
|
||||
description: Current best practices for Rust projects - cargo, editions, web frameworks, and tooling.
|
||||
tags:
|
||||
- rust
|
||||
- cargo
|
||||
- axum
|
||||
- bootstrap
|
||||
- engineering
|
||||
timestamp: 2026-08-11
|
||||
verified: 2026-08-28
|
||||
---
|
||||
|
||||
CUT
|
||||
# Rust
|
||||
|
||||
This page covers current (2025/2026) best practices for Rust projects.
|
||||
|
||||
## Bootstrap
|
||||
|
||||
Create a binary crate:
|
||||
|
||||
```bash
|
||||
cargo new my-app --bin
|
||||
```
|
||||
|
||||
Create a library crate:
|
||||
|
||||
```bash
|
||||
cargo new my-lib --lib
|
||||
```
|
||||
|
||||
New projects use the Rust 2024 edition by default.
|
||||
|
||||
## Tooling
|
||||
|
||||
| Category | Tool | Notes |
|
||||
|----------|------|-------|
|
||||
| Toolchain | rustup | Install with the rustup script. |
|
||||
| Formatter | rustfmt | Run `cargo fmt`. |
|
||||
| Linter | clippy | Run `cargo clippy --all-targets --all-features`. |
|
||||
| Testing | `cargo test` | Unit tests in `#[cfg(test)]`, integration tests in `tests/`. |
|
||||
| Async runtime | tokio | The standard choice. |
|
||||
|
||||
Use `cargo clippy -- -D warnings` in CI.
|
||||
|
||||
## Workspaces
|
||||
|
||||
Use a Cargo workspace for projects with multiple crates. Declare members in the root `Cargo.toml`.
|
||||
|
||||
```
|
||||
workspace-root/
|
||||
├── Cargo.toml
|
||||
└── crates/
|
||||
├── app/
|
||||
└── core/
|
||||
```
|
||||
|
||||
## Web Frameworks
|
||||
|
||||
| Framework | Best For | Notes |
|
||||
|-----------|----------|-------|
|
||||
| Axum 0.8 | Most Rust web apps | Most popular. Tokio team. |
|
||||
| actix-web | High-throughput services | Slightly faster in benchmarks. |
|
||||
| Rocket | Developer experience | Excellent ergonomics. |
|
||||
|
||||
Use Axum for new web services.
|
||||
|
||||
## Error Handling
|
||||
|
||||
Use `thiserror` for library error types. Use `anyhow` for application-level errors. The `?` operator propagates errors.
|
||||
|
||||
## Desktop and WASM
|
||||
|
||||
* Use Tauri 2 for cross-platform desktop apps with a web frontend.
|
||||
* Use `wasm-pack` and `wasm-bindgen` for WebAssembly.
|
||||
|
||||
## Related Technologies
|
||||
|
||||
* serde and serde_json for serialization.
|
||||
* clap for command-line interfaces.
|
||||
* tracing and tracing-subscriber for structured logging.
|
||||
* sqlx for compile-time checked SQL.
|
||||
* tonic for gRPC.
|
||||
* criterion for benchmarks.
|
||||
|
||||
## Citations
|
||||
|
||||
* [The Cargo Book](https://doc.rust-lang.org/cargo/)
|
||||
* [Axum](https://docs.rs/axum/)
|
||||
* [Tauri](https://v2.tauri.app/)
|
||||
|
||||
## See Also
|
||||
|
||||
* [SDLC and Tooling](../sdlc.md)
|
||||
* [Go](go.md)
|
||||
Reference in New Issue
Block a user