Changelog
Recent changes to the garden.
July 7, 2026
add "Coloring With Code" section for programmatic palette generation
Added
Updated
- Ux
Show diff
diff --git a/src/content/docs/ux/index.md b/src/content/docs/ux/index.md index d89a5a9..0f4f57d 100644 --- a/src/content/docs/ux/index.md +++ b/src/content/docs/ux/index.md @@ -1,15 +1,18 @@ --- title: UX --- Good UX is about making software legible, usable, maintainable, and honest about why it exists. ## Overview - [Structuring CSS](/ux/css/) covers boring, legible vanilla CSS organized around reset, tokens, base styles, utilities, components, and parent-owned spacing. +- [Coloring With Code](/ux/colors/code/) covers programmatic palette + generation, color spaces, hue rotation, discovery palettes, hue-shifted + ramps, and color-mixing caveats. - [Narrative](/ux/narrative/) contains questions for explaining where software came from, who made it, why it exists, why software was the chosen medium, and what happens when it changes or disappears.
July 6, 2026
better excerpt extraction (no mdx artifacts)
Updated
- Home
Show diff
diff --git a/src/content/docs/index.md b/src/content/docs/index.md index 124146a..1d01f95 100644 --- a/src/content/docs/index.md +++ b/src/content/docs/index.md @@ -1,27 +1,27 @@ --- title: Welcome description: desertthunder's digital garden homepage --- Hi! My name is Owais and this is my digital garden. It's a collection of notes I've taken on topics that interest me. This includes a lot of engineering and programming notes that I've taken (and continue to take) throughout my career and while working on personal projects. My hope is that someone learns something new or finds some wisdom that resonates with them. -Digital gardens fascinated me for a long time. I miss the days of stumbling upon +Digital gardens have fascinated me for a long time. I miss the days of stumbling upon the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos of digital gardens. Also, take a look at my notes on [cultivating](/writing/cultivation/) a garden.
update image configuration
Moved / renamed
- Information Civics from Information Civics
add eldritch theme
Updated
- Home
Show diff
diff --git a/src/content/docs/index.md b/src/content/docs/index.md index e1c19b4..124146a 100644 --- a/src/content/docs/index.md +++ b/src/content/docs/index.md @@ -18,19 +18,20 @@ on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos of digital gardens. Also, take a look at my notes on [cultivating](/writing/cultivation/) a garden. ### Themes This site includes theme palettes adapted from: - [Cyberdream](https://github.com/scottmckendry/cyberdream.nvim) +- [Eldritch](https://github.com/eldritch-theme/eldritch.nvim) - [Iceberg](https://github.com/cocopon/iceberg.vim) - [Oxocarbon](https://github.com/nyoom-engineering/oxocarbon.nvim) - [Spaceduck](https://github.com/pineapplegiant/spaceduck) - [Thorn](https://github.com/jpwol/thorn.nvim)
feat: add theme switcher and update styles for multiple themes
Updated
- Home
Show diff
diff --git a/src/content/docs/index.md b/src/content/docs/index.md index 71c42e9..e1c19b4 100644 --- a/src/content/docs/index.md +++ b/src/content/docs/index.md @@ -12,15 +12,25 @@ new or finds some wisdom that resonates with them. Digital gardens fascinated me for a long time. I miss the days of stumbling upon the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos of digital gardens. Also, take a look at my notes on [cultivating](/writing/cultivation/) a garden. + +### Themes + +This site includes theme palettes adapted from: + +- [Cyberdream](https://github.com/scottmckendry/cyberdream.nvim) +- [Iceberg](https://github.com/cocopon/iceberg.vim) +- [Oxocarbon](https://github.com/nyoom-engineering/oxocarbon.nvim) +- [Spaceduck](https://github.com/pineapplegiant/spaceduck) +- [Thorn](https://github.com/jpwol/thorn.nvim)
update tags
Updated
- Bobby Bonilla
Show diff
diff --git a/src/content/docs/culture/baseball/bobby-bonilla.md b/src/content/docs/culture/baseball/bobby-bonilla.md index 424c7d5..f6082a7 100644 --- a/src/content/docs/culture/baseball/bobby-bonilla.md +++ b/src/content/docs/culture/baseball/bobby-bonilla.md @@ -1,18 +1,21 @@ --- title: Bobby Bonilla Day featured: 10 +tags: + - baseball + - finance --- On July 1st of every year the New York Mets pay Bonilla $1,193,248.20 under a deferred-compensation agreement. The payments started in 2011 and continue every July 1 through 2035, even though Bonilla last played for the Mets in 1999 and last appeared in MLB in 2001.[^1] Bonilla still gets a seven-figure baseball check long after retirement. The contract itself is straightforward: the Mets converted \$5.9 million owed for the 2000 season into roughly \$29.8 million paid over 25 years.[^2] ## History In January 2000, the Mets wanted to move on from Bonilla but still owed him $5.9 million. - Compound
Show diff
diff --git a/src/content/docs/engineering/ai/compound.md b/src/content/docs/engineering/ai/compound.md index 6c1a973..46b8792 100644 --- a/src/content/docs/engineering/ai/compound.md +++ b/src/content/docs/engineering/ai/compound.md @@ -1,144 +1,193 @@ --- title: Compound Engineering tags: - ai - engineering - agents -source: https://every.to/guides/compound-engineering -author: Kieran Klaassen and Claude -date: not listed on the captured page -captured: 2026-07-03 --- -## Summary +Compound engineering is an AI-assisted development loop where each task improves +the system that will handle the next task.[^compound] -Compound engineering is an AI-native development philosophy where every unit -of work should make future work easier by turning decisions, fixes, patterns, -and taste into reusable system context. +The normal loop is: -## Key Ideas +```text +Plan -> Work -> Review -> Compound -> Repeat +``` -- **The loop is plan → work → review → compound:** Planning defines the work, agents execute it, review catches problems, and the compound step teaches the system so the next task is easier. -- **The compound step is the differentiator:** Without documenting patterns, updating agent instructions, and creating reusable tools, AI-assisted development remains ordinary development with faster typing. -- **Plans become the main artifact:** A good plan captures requirements, tradeoffs, files, edge cases, and acceptance criteria before code exists, making agent execution and later review cheaper. -- **Taste should move out of people’s heads:** Preferences about naming, architecture, testing, copy, and design should be encoded in `CLAUDE.md`, `AGENTS.md`, skills, commands, review agents, and docs. -- **Trust comes from safety nets, not constant supervision:** Tests, review agents, logs, worktrees, PRs, and rollback paths are more scalable than approving every line manually. -- **Agent-native environments reduce manual glue work:** If agents cannot run tests, inspect logs, create PRs, view screenshots, or access debugging data, humans inherit those tasks. -- **Parallel work changes the bottleneck:** Human attention used to be the bottleneck; in this model, compute and coordination become the bottlenecks. +The first three steps ship the current change. The compound step captures what +the system learned: plans, patterns, bug fixes, review findings, tests, prompts, +agent instructions, commands, and reusable tools.[^compound] -### Each task should make later tasks easier +## Main Idea -The article argues that normal codebases get harder to change because each -feature adds complexity. Compound engineering reverses this by using bug fixes, -plans, reviews, and patterns as material for future automation and documentation. +Normal codebases tend to get harder to change as features accumulate. Compound +engineering tries to reverse that by treating every feature and bug fix as raw +material for future automation. -**Confidence:** high for the philosophy; the source offers a clear mechanism -but not quantitative proof. +A bug fix should prevent a class of future bugs. A review finding should become +a test, checklist item, style rule, or reviewer instruction. A repeated manual +workflow should become a command or script. -### AI-assisted work needs more planning and review, not less +This is the useful part of the idea. AI makes the compounding loop cheaper +because agents can help plan, implement, review, and document the pattern. But +the loop is not about typing faster. It is about making the development system +less dependent on private memory. -The authors recommend spending most feature time on planning and review, with -implementation and compounding taking the smaller share. +## Planning -Their rationale is that agent execution is only as good as the plan and feedback -loop that guide it. +The article's strongest claim is that planning becomes the main artifact. +Klaassen and Claude phrase it as "Plans are the new code."[^plans] -**Confidence:** medium; plausible, but the specific time split is experiential -rather than empirically established. +A useful plan captures: -### System improvement should be treated as feature work +- what is being built and why; +- relevant files and existing patterns; +- external docs and best practices; +- constraints and tradeoffs; +- edge cases; +- tests and acceptance criteria; +- review focus. -The article proposes a broader 50/50 allocation: half of engineering time -building features, half improving the system that builds features. Examples -include creating review agents, documenting patterns, and building generators. +This matters more with agents because execution is cheap. If the plan is vague, +the agent fills gaps with guesses. If the plan is concrete, implementation and +review both get easier. -**Confidence:** medium; the article gives concrete examples, but the exact -ratio is a heuristic. +## Review -### Manual line-by-line review does not scale +Manual line-by-line supervision does not scale well when agents can produce +large changes quickly. The replacement is not blind trust. It is a better review +system: -The source claims that if engineers cannot trust AI output, they should improve -the system instead of compensating with constant manual review. Review agents, -tests, monitoring, and explicit PR review are the proposed replacements. +- tests, linting, type checks, and screenshots; +- specialized review agents; +- explicit priority levels for findings; +- isolated branches or worktrees; +- logs, rollback paths, and PR checks; +- a final human review of the important decisions. -**Confidence:** medium; this depends heavily on codebase risk, team maturity, -and quality of verification. +The article recommends capturing review findings as patterns so the next cycle +can catch the same issue earlier.[^compound] -### Agent-native architecture makes AI more useful +## Parallel Work -The source defines agent-native architecture as giving agents the same relevant -capabilities humans have: running local apps, tests, linters, migrations, git -operations, logs, screenshots, network inspection, and error tracking. +When agents make implementation cheaper, the bottleneck moves from typing to +coordination. Independent tasks can run in parallel, but shared files, shared +schemas, and ambiguous ownership still create conflicts. -**Confidence:** high as a practical checklist; security and production -permissions still need boundaries. +The practical rule is to parallelize work with clean boundaries: one feature +area, one review pass, one test-writing task, or one research task. Serial work +still makes sense when the next task depends on decisions from the previous one. -### Compound engineering extends beyond coding +## Compounding -The article applies the same loop to design, user research, data analysis, -copywriting, and product marketing: structure context, generate artifacts, -review them, and encode what worked for reuse. +The compound step asks: -**Confidence:** medium; useful pattern, but some sections are sketches rather -than complete processes. +- What worked? +- What failed? +- What pattern should be reusable? +- Where should that pattern live? +- Would the system catch this next time? -## Important Terms +The answer might be an `AGENTS.md` rule, a `CLAUDE.md` update, a test, a local +command, a review prompt, an architecture note, a generator, or a runbook. -| Term | Meaning | -| ------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| Compound engineering | A development approach where each task updates the system so future tasks become easier. | -| Compound step | The post-review step that captures lessons, documents patterns, updates agent context, and creates reusable tools. | -| Agent-native architecture | Project and environment design that lets agents inspect, modify, test, debug, and ship work with minimal human glue. | -| Plan-first development | Writing and reviewing the plan before implementation so the agent has a source of truth. | -| Taste extraction | Encoding a team’s preferences into docs, prompts, skills, commands, and automated reviewers. | -| Vibe coding | Fast outcome-oriented prototyping where the user cares about the result more than the implementation details. | -| Safety nets | Tests, reviewers, isolation, logs, rollbacks, and PR checks that make autonomous agent work safer. | +The important distinction is findability. Capturing a lesson in a private chat +log does not compound much. Capturing it in the repo, with useful names and +metadata, gives later agents and humans a chance to retrieve it. -## Questions for Review +## Agent-Native Architecture -- What makes compound engineering different from ordinary AI-assisted coding? -- Why is the compound step more important than the implementation step? -- What kinds of team “taste” can be extracted into system context? -- Why do plans become more important when agents write more of the code? -- What capabilities would an agent need to work in an agent-native environment? -- When might vibe coding be useful, and when would it be risky? -- What replaces manual line-by-line review in the compound engineering model? +An agent-native environment gives agents the same relevant development surfaces +humans use: -## Connections +- file access; +- test, lint, typecheck, and build commands; +- local app inspection; +- browser and screenshot access; +- logs and error output; +- issue, PR, and review context; +- rollback and isolation tools. -- Related ideas: continuous improvement, knowledge management, test - automation, platform engineering, agentic workflows. -- Related sources: `AGENTS.md`, `CLAUDE.md`, architecture decision records, - style guides, runbooks, postmortems. -- Tensions: autonomy vs. control; velocity vs. safety; reusable system context - vs. documentation overhead. -- Useful applications: recurring bug prevention, onboarding, review automation, - design system capture, release notes, changelog generation. +The article describes this as progressive rather than all-or-nothing. Basic +file and test access is the starting point. Browser access, logs, and PR +creation come later as trust and safety nets improve.[^compound] -## Open Questions +Production access still needs boundaries. "Agent-native" should not mean every +agent can mutate secrets, infrastructure, or customer data. -- How should teams measure whether compounding work is actually making - future work faster? -- Which tasks are safe to parallelize, and which must remain serial to avoid - coordination failures? -- How much production access should agents receive, even read-only? -- What is the minimum useful version of this workflow for a small project? -- How do teams keep agent instructions and skills from becoming stale or - contradictory? +## Taste Extraction -## Notable Quotes +Compound engineering depends on moving taste out of people's heads. Naming, +architecture, testing preferences, UI standards, copy tone, and review habits +should become written context or executable checks. -> “Each unit of engineering work should make subsequent units easier—not harder.” +This is especially useful for small teams. If one person is carrying the whole +style guide in memory, agents and teammates will keep rediscovering it through +review comments. ---- +## Vibe Coding + +The source uses "vibe coding" for fast, outcome-oriented prototyping where the +developer cares more about the result than the implementation details. That can +be useful for sketches, demos, and throwaway experiments. + +It is risky when the code becomes production software. At that point, the work +needs plans, tests, review, and a compound step so the system can explain and +maintain what was built. + +## Beyond Code + +The same loop can apply outside implementation: + +- product research becomes structured planning context; +- design feedback becomes design-system rules; +- copy review becomes voice and terminology guidance; +- analytics work becomes reusable queries and dashboards. + +The common shape is the same: do the work, review the output, then encode the +learning somewhere future work can use it. + +## Tensions + +The article gives a strong operating model, but several parts are heuristics. +The suggested time split, including heavy emphasis on planning and review, is +experience-based rather than measured proof.[^compound] + +The risky failure modes are predictable: + +- documentation can become stale; +- agents can optimize for written rules while missing intent; +- parallel work can create coordination conflicts; +- too much autonomy can outrun the available safety nets; +- compounding work can become busywork if nobody retrieves it later. + +The practical test is simple: does the captured lesson reduce future review +time, prevent a repeated bug, or make onboarding easier? If not, it may not be +worth keeping. + +## Terms + +| Term | Meaning | +| ------------------------- | -------------------------------------------------------------------------------------------- | +| Compound engineering | A development approach where each task updates the system so future tasks become easier. | +| Compound step | The post-review step that captures lessons, documents patterns, and creates reusable tools. | +| Agent-native architecture | Project and environment design that lets agents inspect, test, debug, and ship work. | +| Plan-first development | Writing and reviewing a plan before implementation starts. | +| Taste extraction | Encoding a team's preferences into docs, prompts, skills, commands, and automated reviewers. | +| Vibe coding | Fast outcome-oriented prototyping where implementation details are secondary. | +| Safety nets | Tests, reviewers, isolation, logs, rollbacks, and PR checks that make autonomous work safer. | -> “Plans are the new code.” +## Questions -## Takeaways +- What kinds of team taste should be encoded in project files? +- Which repeated review findings should become tests? +- Which tasks are safe to parallelize? +- How much local or production access should agents receive? +- How can a team measure whether compounding work is actually paying off? +- What is the smallest useful version of this loop for a solo project? +- What replaces manual line-by-line review in this model? -- Treat every bug fix, review finding, and design decision as reusable system - knowledge. -- Build trust by improving plans, tests, reviewers, and rollback paths rather - than watching every generated line. -- The long-term payoff comes from teaching the system instead of just shipping - the current feature. +[^compound]: + Kieran Klaassen and Claude, "Compound Engineering," Every, + <https://every.to/guides/compound-engineering>. Accessed 6 Jul. 2026. - Specs
Show diff
diff --git a/src/content/docs/engineering/ai/specs.md b/src/content/docs/engineering/ai/specs.md index 80e3d1f..91c67c6 100644 --- a/src/content/docs/engineering/ai/specs.md +++ b/src/content/docs/engineering/ai/specs.md @@ -1,145 +1,225 @@ --- title: Specs for AI Agents tags: - ai - engineering - agents - specs -source: https://addyosmani.com/blog/good-spec/ -author: Addy Osmani -date: 2026-01-13 -captured: 2026-07-03 --- -## Summary +An AI agent spec is a structured document that tells a coding agent what to +build, how to work, what to test, and what not to touch. -Good specs for AI coding agents are clear, structured, scoped, testable, and -continuously updated: enough context to guide the agent, not so much that it -loses focus. +The spec should be clear enough to prevent guessing, but focused enough that the +agent can use it. Addy Osmani's rule is useful: minimal does not have to mean +short.[^osmani] -## Key Ideas +## Start With Vision -- **Start with the vision:** Give the agent a concise goal, user need, and core - requirements, then use the agent to draft a more detailed spec. -- **Plan before coding:** Read-only planning modes help the agent explore the - codebase, ask clarifying questions, and produce a plan before it edits files. -- **Use a professional structure:** A useful spec looks more like a PRD/SRS - than a loose prompt. It should include objective, stack, commands, tests, - structure, style, workflow, and boundaries. -- **Keep context modular:** Feed the agent the relevant slice of the spec for - the current task instead of dumping a giant document into every prompt. -- **Build in verification:** Specs should include tests, acceptance criteria, - self-checks, boundaries, and review steps so the agent can compare its work - against the requirements. -- **Treat specs as living artifacts:** Update the spec when requirements, - architecture, data models, or constraints change; commit it with the - project like code. -- **Human judgment remains required:** The spec improves agent behavior, but - the developer still owns quality, intent, tradeoffs, and critical review. +Start with the user need, the goal, and the success criteria. Let the agent help +expand that into a fuller spec, but keep control of the direction. -### Massive specs can make agents worse, not better +The first version should answer: -Osmani argues that context window limits and limited model attention make -large undifferentiated specs unreliable. Long contexts should be summarized, -indexed, split into component specs, or retrieved only when relevant. +- Who is this for? +- What problem does it solve? +- What does success look like? +- What constraints are already known? +- What should stay out of scope? -**Confidence:** high; this matches the article’s core rationale, though exact -failure thresholds depend on model and task. +This keeps the agent from optimizing for implementation details before it knows +the purpose. -### The best specs cover six recurring areas +## Plan Before Coding -The article cites GitHub analysis of more than 2,500 agent configuration files -and says effective specs usually include commands, testing, project structure, -code style, git workflow, and boundaries. +Read-only planning modes are useful because they let the agent inspect the +codebase, identify patterns, ask questions, and write a plan before touching +files.[^osmani] -**Confidence:** medium-high; the checklist is concrete and practical, but the -article does not reproduce the underlying dataset. +A good planning phase produces: -### Specs should be executable parts of the workflow +- relevant files and existing patterns; +- proposed steps; +- risks and unknowns; +- test strategy; +- acceptance criteria; +- questions that need a human answer. -Rather than writing a spec and ignoring it, Osmani recommends a gated flow: -specify, plan, break into tasks, implement, and verify each phase before moving on. +Do not skip review of the plan. If the plan is wrong, the implementation will +usually be wrong faster. -**Confidence:** high as a workflow recommendation; the specific tools are optional. +## Structure -### Small focused tasks outperform one giant prompt +Osmani recommends treating the spec more like a PRD or SRS than a loose prompt. +GitHub's analysis of more than 2,500 agent configuration files found six +recurring areas in useful agent instructions: commands, testing, project +structure, code style, git workflow, and boundaries.[^osmani] -The article recommends breaking implementation into phases or components, -passing only the relevant spec section, and starting fresh when switching major -features. +A practical spec outline: -**Confidence:** high; the mechanism is clear: less irrelevant context reduces -instruction conflicts and attention dilution. +```md +# Feature Spec -### Constraints need nuance +## Objective -A useful spec should distinguish between actions the agent may always take, -actions requiring human approval, and actions it must never take. This is -better than a flat list of prohibitions. +## Users and Use Cases -**Confidence:** high as a practical pattern. +## Requirements -### Tests give agents a feedback loop +## Non-Goals -Tests, conformance suites, linting, and explicit success criteria let agents -iterate: write code, run checks, inspect failures, fix, and repeat. +## Tech Stack -**Confidence:** high; automated checks are one of the strongest ways to turn a -spec into enforceable behavior. +## Commands -## Important Terms +## Project Structure -| Term | Meaning | -| --------------------- | --------------------------------------------------------------------------------------------------------------------- | -| AI agent spec | A structured document that tells a coding agent what to build, how to work, what to test, and what not to touch. | -| PRD | Product Requirements Document; user-centered description of what problem is being solved and what success looks like. | -| SRS | Software Requirements Specification; more detailed technical requirements for implementation. | -| Plan Mode | A read-only planning phase where the agent can inspect and design but not edit code. | -| Agent Experience (AX) | Designing docs, schemas, commands, and project structure so agents can reliably consume and act on them. | -| Three-tier boundaries | Rules grouped into always do, ask first, and never do. | -| Conformance tests | Spec-derived tests that any implementation must pass, often reusable across implementations. | -| LLM-as-a-Judge | A second model or agent reviewing output against subjective criteria such as style or architecture. | +## Code Style -## Questions for Review +## Boundaries -- Why should an AI agent spec start with vision before implementation detail? -- What six areas should a strong coding-agent spec cover? -- Why can too much context reduce an agent’s reliability? -- What is the difference between “always,” “ask first,” and “never” constraints? -- How do tests and conformance suites make specs more enforceable? -- When is a lightweight prompt enough, and when is a full spec necessary? -- Why should specs be version-controlled and updated like code? +## Test Plan -## Connections +## Acceptance Criteria +``` -- Related ideas: spec-driven development, PRDs, SRS documents, test-driven - development, acceptance criteria, executable documentation. -- Related sources: `AGENTS.md`, `CLAUDE.md`, project READMEs, architecture - docs, test plans, CI configuration. -- Tensions: detail vs. overload; automation vs. human review; fast prototyping - vs. production engineering. -- Useful applications: onboarding agents to a repo, writing feature plans, - constraining autonomous edits, turning requirements into testable tasks. +Commands should be executable, not vague. `pnpm test`, `pytest -v`, or +`cargo test` is more useful than "run the tests." -## Open Questions +## Workflow -- How detailed should a spec be for different task sizes? -- Which parts of a spec belong in a durable project file versus a one-off prompt? -- How should teams detect that a spec has become stale? -- What tooling best connects specs to tests, CI, and agent context retrieval? -- How can teams measure whether better specs reduce review time or rework? +A spec is more useful when it drives the work instead of sitting beside it. +Osmani describes a gated flow: -## Notable Quotes +1. Specify the user experience and success criteria. +2. Plan the technical approach. +3. Break the plan into small tasks. +4. Implement each task and verify it before moving on.[^osmani] -> “Minimal does not necessarily mean short.” +That shape keeps review focused. Instead of reviewing one large generated +change, the human can review the spec, the plan, the task breakdown, and then +the implementation. ---- +## Context Size + +Large undifferentiated specs can make agents worse. Context windows are finite, +and models do not pay equal attention to every instruction.[^osmani] + +Split large specs by phase or component: + +- backend API; +- frontend UI; +- data model; +- migration plan; +- security requirements; +- test plan. + +Then feed the agent the relevant slice for the current task. A compact table of +contents or section summary can stay in context while full details are retrieved +only when needed. + +Recent AGENTS.md research points in the same direction. One 2026 study found +that unnecessary repository context can reduce task success while increasing +cost, even though agents do tend to follow the instructions they are given.[^agents-eval] +Another cataloged common configuration smells: context bloat, skill leakage, +lint leakage, blind references, init fossilization, and conflicting +instructions.[^agents-smells] + +## Boundaries + +Flat "do not do this" lists are weaker than tiered boundaries. + +| Tier | Meaning | Examples | +| --------- | ------------------------------------- | ------------------------------------------------ | +| Always | The agent can do this without asking. | Run tests, follow formatting, update docs. | +| Ask first | The agent must pause for approval. | Add dependencies, change schemas, edit CI. | +| Never | The agent must not do this. | Commit secrets, edit vendor files, delete tests. | + +The point is to make the safe path explicit. The agent should know when to +continue, when to ask, and when to stop.[^osmani] + +## Verification + +Specs work best when they include checks the agent can run. + +Good verification material: -> “A spec for an AI agent isn’t ‘write once, done.’” +- unit, integration, and end-to-end test commands; +- lint and typecheck commands; +- conformance fixtures; +- expected input/output examples; +- screenshot or visual review requirements; +- self-check questions; +- review-agent prompts for subjective criteria. -## Takeaways +Tests give the agent a feedback loop: implement, run checks, inspect failures, +fix, and repeat. Conformance suites are especially useful when the same contract +should hold across implementations.[^osmani] -- Write specs that are clear, scoped, structured, and testable. -- Give agents only the context they need for the current task. -- Keep the spec alive: update it, version it, and use it as the source of truth - for planning, implementation, and review. +LLM-as-a-judge can help with subjective criteria such as style, accessibility, +or architecture, but it should supplement deterministic checks rather than +replace them. + +## Living Document + +A spec that is not updated becomes misleading context. Update it when the data +model changes, a requirement is cut, an edge case is discovered, or the team +chooses a new convention.[^osmani] + +Version it with the project. The spec is useful to agents because it is also +useful to humans returning to the code later. + +## When To Keep It Small + +Not every task needs a full PRD. For a small isolated change, a focused prompt +plus the relevant commands may be enough. + +Use a heavier spec when the task has: + +- multiple files or phases; +- data model changes; +- security, privacy, or migration risk; +- design or copy requirements; +- ambiguous product behavior; +- expensive review if the first pass is wrong. + +The skill is matching spec weight to task risk. + +## Terms + +| Term | Meaning | +| --------------------- | -------------------------------------------------------------------------------------------------------- | +| AI agent spec | A structured document that guides a coding agent's work, checks, and boundaries. | +| PRD | Product Requirements Document; user-centered description of the problem and success criteria. | +| SRS | Software Requirements Specification; detailed technical requirements for implementation. | +| Plan Mode | Read-only planning phase where an agent can inspect and design before editing code. | +| Agent Experience | Designing docs, schemas, commands, and project structure so agents can reliably consume and act on them. | +| Three-tier boundaries | Rules grouped into always do, ask first, and never do. | +| Conformance tests | Spec-derived tests that any implementation must pass. | +| LLM-as-a-judge | A second model or agent reviewing output against criteria that are hard to test deterministically. | + +## Questions + +- What six areas should a strong coding-agent spec cover? +- Which parts of the spec belong in durable project files versus one-off + prompts? +- Where does too much context start hurting the agent? +- Which constraints should be always, ask first, or never? +- What tests make the spec enforceable? +- How will the team notice when the spec becomes stale? + +[^osmani]: + Addy Osmani, "How to write a good spec for AI agents," 13 Jan. 2026, + <https://addyosmani.com/blog/good-spec/>. Accessed 6 Jul. 2026. + +[^agents-eval]: + Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, + and Martin Vechev, "Evaluating AGENTS.md: Are Repository-Level Context Files + Helpful for Coding Agents?" arXiv, 12 Feb. 2026, + <https://arxiv.org/abs/2602.11988>. Accessed 6 Jul. 2026. + +[^agents-smells]: + Helio Victor F. dos Santos, Vitor Costa, Joao Eduardo + Montandon, Luciana Lourdes Silva, and Marco Tulio Valente, "Configuration + Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents," + arXiv, 14 Jun. 2026, <https://arxiv.org/abs/2606.15828>. Accessed 6 Jul. 2026. - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index 9c9bfb5..f34c089 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -1,18 +1,22 @@ --- title: How to Be Perfect featured: 30 +tags: + - philosophy + - ethics + - morality --- import Aside from "../../../components/Aside.astro"; Written by the venerable Michael Schur, creator of Parks & Recreation and of course, The Good Place. --- - Morality is how we think we should behave on earth <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> - Beam
Show diff
diff --git a/src/content/docs/programming/beam/beam.md b/src/content/docs/programming/beam/beam.md index fda50a1..7a550f1 100644 --- a/src/content/docs/programming/beam/beam.md +++ b/src/content/docs/programming/beam/beam.md @@ -1,47 +1,53 @@ --- title: The BEAM featured: 40 +tags: + - elixir + - erlang + - beam + - otp + - genserver --- The BEAM (Berkeley Erlang Abstract Machine) is the virtual machine that runs Elixir and Erlang programs. In addition to being a bytecode executor, it provides: - massive concurrency - fault tolerance - message passing - process isolation - hot code loading - distributed systems - long-running services Erlang processes are lightweight, fast to create and terminate, dynamically sized, and have low scheduling overhead, according to the Erlang system documentation. Originally developed at Ericsson (a telecom company), it was built as a runtime for building many small isolated workers that communicate by messages and can be restarted when they fail. ## Fault Tolerance Fault tolerance is handled through supervision trees. Supervisors[^sup] are processes that monitor and restart other processes when they fail. Instead of treating crashes as catastrophic, design systems so that small parts can fail and recover. ## OTP OTP stands for Open Telecom Platform, but the name is historical. In modern Elixir/Erlang, OTP means "The standard framework, libraries, and design patterns for building reliable BEAM applications." ## GenServer GenServer is a behavior that provides a standardized way to implement stateful processes in Elixir/Erlang. OTP[^otp] standardizes how they behave. They have: - has state - receives & responds to messages - handles async casts - supervision - lifecycle callbacks -[^otp]: Introduction. https://erlang.org/documentation/doc-5.2/doc/system_architecture_intro/sys_arch_intro.html. Accessed 31 May 2026. +[^otp]: Introduction. <https://erlang.org/documentation/doc-5.2/doc/system_architecture_intro/sys_arch_intro.html>. Accessed 31 May 2026. -[^sup]: Supervision Principles. https://erlang.org/documentation/doc-4.9.1/doc/design_principles/sup_princ.html. Accessed 31 May 2026. +[^sup]: Supervision Principles. <https://erlang.org/documentation/doc-4.9.1/doc/design_principles/sup_princ.html>. Accessed 31 May 2026. - Trees
Show diff
diff --git a/src/content/docs/programming/data_structures/trees.md b/src/content/docs/programming/data_structures/trees.md index 6bb27b4..93f9424 100644 --- a/src/content/docs/programming/data_structures/trees.md +++ b/src/content/docs/programming/data_structures/trees.md @@ -1,17 +1,21 @@ --- title: Trees +tags: + - programming + - data structures + - trees --- *"All roads lead to trees."* Examples: DOM, Filesystem (hard drive) ## Terminology - root: topmost parent node - height: longest path from root the youngest (bottommost) child node - binary tree: a tree with at most 2 children - general tree: a tree with more than 0 children - balanced tree: a tree is perfectly balanced when any node's left and right children have the same height - branching factor: amount of children a tree has ## Traversal - Done
Show diff
diff --git a/src/content/docs/psychology/done.md b/src/content/docs/psychology/done.md index 2bcb279..745ef6a 100644 --- a/src/content/docs/psychology/done.md +++ b/src/content/docs/psychology/done.md @@ -1,18 +1,21 @@ --- title: The Cult of Done Manifesto featured: 20 +tags: + - psychology + - productivity --- Source[^1] 1. There are three states of being. Not knowing, action and completion. 2. Accept that everything is a draft. It helps to get it done. 3. There is no editing stage. 4. Pretending you know what you’re doing is almost the same as knowing what you are doing, so just accept that you know what you’re doing even if you don’t and do it. 5. Banish procrastination. If you wait more than a week to get an idea done, abandon it. 6. The point of being done is not to finish but to get other things done. 7. Once you’re done you can throw it away. 8. Laugh at perfection. It’s boring and keeps you from being done.
July 3, 2026
add a prompt
Added
android usage stats shortcut
Added
June 27, 2026
collapsible sidebars
Updated
- Programming
Show diff
diff --git a/src/content/docs/programming/index.md b/src/content/docs/programming/index.md index e093a0d..f89aa80 100644 --- a/src/content/docs/programming/index.md +++ b/src/content/docs/programming/index.md @@ -1,17 +1,17 @@ --- -title: On Programming +title: Programming --- This will contain notes related to programming languages I've "learned" or am learning. Can you ever really know a programming language top to bottom unless you wrote it? ## Proficiencies Updated June 2026 - TypeScript - Python - Java - Ruby - Go
fix active state for nested notes
Updated
- Leverage
Show diff
diff --git a/src/content/docs/culture/baseball/leverage.md b/src/content/docs/culture/baseball/leverage.md index b2e592a..d567760 100644 --- a/src/content/docs/culture/baseball/leverage.md +++ b/src/content/docs/culture/baseball/leverage.md @@ -1,49 +1,59 @@ --- title: Leverage Index +tags: + - baseball + - statistics --- How important is *this* plate appearance, relative to an average one? ## What is Leverage / Leverage Index? Leverage Index was created by Tom Tango to measure **how much the win probability could swing** on the next play, given the current game state (inning, score, outs, baserunners). A value of: - **1.0** = "neutral" situation (average plate appearance) - **> 1.0** = high leverage (big potential swing in win probability) - **< 1.0** = low leverage (blowouts, early innings with no one on, etc.)[^1] When people talk about "leverage" for a pitcher (especially relievers), they usually mean: - **Average Leverage Index (aLI)** - the average LI of all plate appearances they faced. - **gmLI / inLI** - game-entering or entry leverage when they first appear[^2] ## How is Leverage Index calculated? High-level formula: 1. Take current **Win Expectancy (WE₀)** for the batting team given: - inning - score differential - outs - base state 2. Enumerate the **possible outcomes** of the plate appearance: - out, walk, single, double, HR, etc. 3. For each outcome *i*: - Compute **WEᵢ** = win expectancy after that outcome - Let **ΔWEᵢ = |WEᵢ − WE₀|** (absolute change in win probability) - Weight it by the probability **pᵢ** of that outcome 4. Compute the **expected absolute swing in WE** for this PA: - $\text{Swing}_\text{this PA} = \sum_i p_i \cdot |\text{WE}_i - \text{WE}_0|$ + $$ + \text{Swing}_\text{this PA} = \sum_i p_i \cdot |\text{WE}_i - \text{WE}_0| + $$ + 5. Compute the **average swing** over *all* plate appearances in your dataset: - $\text{Swing}_\text{avg} = \text{mean over all PA of } \sum_i p_i \cdot |\text{WE}_i - \text{WE}_0|$ + $$ + \text{Swing}_\text{avg} = \text{mean over all PA of } \sum_i p_i \cdot |\text{WE}_i - \text{WE}_0| + $$ 6. The **Leverage Index (LI)** of this state is: - $LI = \frac{\text{Swing}*\text{this PA}}{\text{Swing}*\text{avg}}$ + $$ + LI = \frac{\text{Swing}*\text{this PA}}{\text{Swing}*\text{avg}} + $$ This is exactly how FanGraphs and others describe it: expected WE swing for this state, divided by the league-wide average swing[^2] [^1]: <https://www.mlb.com/glossary/advanced-stats/leverage-index> "Leverage Index (LI)" [^2]: <https://library.fangraphs.com/misc/li/> "LI - Sabermetrics Library - FanGraphs"
featured notes
Updated
- Bobby Bonilla
Show diff
diff --git a/src/content/docs/culture/baseball/bobby-bonilla.md b/src/content/docs/culture/baseball/bobby-bonilla.md index 645102e..424c7d5 100644 --- a/src/content/docs/culture/baseball/bobby-bonilla.md +++ b/src/content/docs/culture/baseball/bobby-bonilla.md @@ -1,17 +1,18 @@ --- title: Bobby Bonilla Day +featured: 10 --- On July 1st of every year the New York Mets pay Bonilla $1,193,248.20 under a deferred-compensation agreement. The payments started in 2011 and continue every July 1 through 2035, even though Bonilla last played for the Mets in 1999 and last appeared in MLB in 2001.[^1] Bonilla still gets a seven-figure baseball check long after retirement. The contract itself is straightforward: the Mets converted \$5.9 million owed for the 2000 season into roughly \$29.8 million paid over 25 years.[^2] ## History In January 2000, the Mets wanted to move on from Bonilla but still owed him $5.9 million. - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index 9de01d9..9c9bfb5 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -1,17 +1,18 @@ --- title: How to Be Perfect +featured: 30 --- import Aside from "../../../components/Aside.astro"; Written by the venerable Michael Schur, creator of Parks & Recreation and of course, The Good Place. --- - Morality is how we think we should behave on earth <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> - Recursive Descent
Show diff
diff --git a/src/content/docs/programming/algorithms/recursive-descent.md b/src/content/docs/programming/algorithms/recursive-descent.md index c0cc1e4..b011468 100644 --- a/src/content/docs/programming/algorithms/recursive-descent.md +++ b/src/content/docs/programming/algorithms/recursive-descent.md @@ -1,17 +1,18 @@ --- title: Recursive descent parsing +featured: 80 tags: - algorithms - compilers - parsing --- A *recursive descent parser* (RDP) is a **top-down** parser where each nonterminal of a context-free grammar is implemented as a (mutually) recursive procedure. It parses from left to right, expanding productions according to the grammar and the current lookahead token.[^1] For *predictive* recursive descent (no backtracking), the grammar is typically in the LL(1) family: the next production can be chosen using a fixed, small lookahead (often one token).[^3] Key consequences: - Parser structure mirrors the grammar, which makes RDP ideal for *handwritten* parsers and small DSLs.[^2] - Beam
Show diff
diff --git a/src/content/docs/programming/beam/beam.md b/src/content/docs/programming/beam/beam.md index cea6d19..fda50a1 100644 --- a/src/content/docs/programming/beam/beam.md +++ b/src/content/docs/programming/beam/beam.md @@ -1,17 +1,18 @@ --- title: The BEAM +featured: 40 --- The BEAM (Berkeley Erlang Abstract Machine) is the virtual machine that runs Elixir and Erlang programs. In addition to being a bytecode executor, it provides: - massive concurrency - fault tolerance - message passing - process isolation - hot code loading - distributed systems - long-running services Erlang processes are lightweight, fast to create and terminate, dynamically sized, and have low scheduling - Algo W
Show diff
diff --git a/src/content/docs/programming/functional_programming/algo-w.md b/src/content/docs/programming/functional_programming/algo-w.md index d647fbd..ad7edcf 100644 --- a/src/content/docs/programming/functional_programming/algo-w.md +++ b/src/content/docs/programming/functional_programming/algo-w.md @@ -1,17 +1,18 @@ --- title: Algorithm W +featured: 70 tags: - functional-programming - programming - type-systems --- Algorithm W is a **syntax-directed** way to *construct* proofs of these judgments and compute principal types. ([Wikipedia][^1]) Algorithm W takes an environment and an expression and returns: ```text W(Γ, e) = (S, τ) ``` meaning: under substitution `S`, `e` has monotype `τ` in environment `SΓ`. - Hindley Milner
Show diff
diff --git a/src/content/docs/programming/functional_programming/hindley_milner.md b/src/content/docs/programming/functional_programming/hindley_milner.md index 4d385f1..4d3fb9d 100644 --- a/src/content/docs/programming/functional_programming/hindley_milner.md +++ b/src/content/docs/programming/functional_programming/hindley_milner.md @@ -1,17 +1,18 @@ --- title: Hindley-Milner +featured: 60 tags: - functional-programming - programming - type-systems --- Hindley–Milner is a type system for the λ-calculus with **parametric polymorphism**. It has two key properties: 1. It can infer types **without annotations**. 2. It computes a **principal type**: the most general type from which all other valid types follow by specialization. ([Wikipedia][^1]) ## HM Types We distinguish: - Zig
Show diff
diff --git a/src/content/docs/programming/zig/index.md b/src/content/docs/programming/zig/index.md index 93066d3..21cef42 100644 --- a/src/content/docs/programming/zig/index.md +++ b/src/content/docs/programming/zig/index.md @@ -1,17 +1,18 @@ --- title: Zig Programming Language +featured: 50 tags: - programming - systems-programming - zig --- Zig is a modern systems programming language that emphasizes safety, performance, and interoperability. ## Imports ```zig const std = @import("std"); ``` - Done
Show diff
diff --git a/src/content/docs/psychology/done.md b/src/content/docs/psychology/done.md index ac6474b..2bcb279 100644 --- a/src/content/docs/psychology/done.md +++ b/src/content/docs/psychology/done.md @@ -1,17 +1,18 @@ --- title: The Cult of Done Manifesto +featured: 20 --- Source[^1] 1. There are three states of being. Not knowing, action and completion. 2. Accept that everything is a draft. It helps to get it done. 3. There is no editing stage. 4. Pretending you know what you’re doing is almost the same as knowing what you are doing, so just accept that you know what you’re doing even if you don’t and do it. 5. Banish procrastination. If you wait more than a week to get an idea done, abandon it. 6. The point of being done is not to finish but to get other things done. 7. Once you’re done you can throw it away. 8. Laugh at perfection. It’s boring and keeps you from being done.
add svelte islands
Added
Updated
- Runes
Show diff
diff --git a/src/content/docs/engineering/web/svelte/runes.md b/src/content/docs/engineering/web/svelte/runes.md index 6b741cd..b05c4fb 100644 --- a/src/content/docs/engineering/web/svelte/runes.md +++ b/src/content/docs/engineering/web/svelte/runes.md @@ -1,226 +1,222 @@ --- title: Runes tags: - frontend - reactivity - svelte --- -Svelte 5 uses runes for explicit component reactivity. This page covers the core state-related runes: `$state`, `$derived`, `$props`, and `$effect`. For SvelteKit server/client state placement, see [Svelte State Management](/engineering/web/svelte/state/). +Svelte 5 uses runes for explicit component reactivity. This page covers the core state-related runes: `$state`, `$derived`, `$props`, and `$effect`. For SvelteKit server/client state placement, see [Svelte State Management](/engineering/web/svelte/state/). For using Svelte as a hydrated widget inside Astro, see [Svelte Islands in Astro](/engineering/web/svelte/islands/). ## What runes are Runes are Svelte 5 syntax that controls the compiler. They begin with `$`, look like function calls, and do not need imports. They are not normal JavaScript values: you cannot assign them to variables or pass them as arguments, and the compiler only allows them in valid positions.[^runes] ```svelte <script> let message = $state('hello'); </script> ``` ## `$state` `$state` creates reactive state. The variable behaves like the value itself rather than like a store object or setter API:[^state] ```svelte <script> let count = $state(0); </script> <button onclick={() => count++}> clicks: {count} </button> ``` When `$state` wraps an array or plain object, Svelte creates a deeply reactive proxy. Mutating a nested property or calling an array method such as `push` triggers granular updates for the parts of the UI that read that property.[^state] ```svelte <script> let todos = $state([{ done: false, text: 'learn runes' }]); </script> <button onclick={() => (todos[0].done = !todos[0].done)}> {todos[0].done ? 'done' : 'not done'} </button> ``` Important details: - Destructuring a reactive value gives you ordinary JavaScript references, not live reactive references.[^state] - Class instances are not proxied, but class fields can use `$state`.[^state] - Use reactive built-ins from `svelte/reactivity` for reactive `Set`, `Map`, `Date`, and `URL`.[^state] - Use `$state.raw` for large objects or arrays that should only update by reassignment, not deep mutation.[^state] - Use `$state.snapshot` when passing a non-proxy copy to APIs or libraries.[^state] - Use `$state.eager` sparingly for immediate visual feedback during synchronized `await` updates.[^state] ## `$derived` `$derived` creates reactive values from other reactive values. Component setup code runs once, so derived expressions are how you keep calculations in sync with changing state or props.[^derived] ```svelte <script> let count = $state(0); let doubled = $derived(count * 2); </script> <button onclick={() => count++}> {count} doubled is {doubled} </button> ``` A `$derived` expression should be free of side effects. Svelte disallows state changes such as `count++` inside derived expressions.[^derived] For multi-line calculations, use `$derived.by`: ```svelte <script> let numbers = $state([1, 2, 3]); let total = $derived.by(() => { let sum = 0; for (const n of numbers) sum += n; return sum; }); </script> ``` Svelte tracks values read synchronously inside the derived expression or function body. Derived values are recalculated lazily when next read, and downstream updates are skipped if the derived value is referentially unchanged.[^derived] Deriveds can also be temporarily reassigned, which is useful for optimistic UI:[^derived] ```svelte <script> let { post, like } = $props(); let likes = $derived(post.likes); async function onclick() { likes += 1; try { await like(); } catch { likes -= 1; } } </script> <button {onclick}>🧡 {likes}</button> ``` ## `$props` `$props` reads component inputs. Most components destructure the returned props object:[^props] ```svelte <script> let { adjective = 'happy' } = $props(); </script> <p>This component is {adjective}</p> ``` Destructuring also supports renaming invalid identifiers, rest props, and TypeScript annotations:[^props] ```svelte <script lang="ts"> interface Props { adjective: string; disabled?: boolean; } let { adjective, disabled = false }: Props = $props(); </script> ``` Props update when the parent updates. A child can temporarily reassign a prop value for local ephemeral state, but it should not mutate props it does not own unless the prop is explicitly bindable. Mutating a reactive proxy passed from a parent can update the UI but causes an ownership warning.[^props] For accessible form fields and labels, `$props.id()` creates an ID unique to the component instance and stable across SSR hydration.[^props] ```svelte <script> const uid = $props.id(); </script> <label for="{uid}-email">Email</label> <input id="{uid}-email" type="email" /> ``` ## `$effect` `$effect` runs side-effecting code when reactive dependencies change. It runs in the browser, not during server-side rendering, after the component has mounted and after DOM updates have been applied.[^effect] Use it for browser effects: third-party libraries, canvas drawing, analytics, subscriptions, timers, or direct DOM work. ```svelte <script> let size = $state(50); let color = $state('#ff3e00'); let canvas; $effect(() => { const context = canvas.getContext('2d'); context.clearRect(0, 0, canvas.width, canvas.height); context.fillStyle = color; context.fillRect(0, 0, size, size); }); </script> <canvas bind:this={canvas} width="100" height="100"></canvas> ``` Svelte tracks reactive values read synchronously inside the effect and reruns the effect when they change. Values read after an `await`, inside `setTimeout`, or in another asynchronous callback are not tracked.[^effect] An effect can return a teardown function. The teardown runs before the effect reruns and when the effect is destroyed:[^effect] ```svelte <script> let count = $state(0); let milliseconds = $state(1000); $effect(() => { const interval = setInterval(() => { count += 1; }, milliseconds); return () => clearInterval(interval); }); </script> ``` Do not use `$effect` to synchronize state that can be expressed as derived state. Prefer this:[^effect] ```svelte <script> let count = $state(0); let doubled = $derived(count * 2); </script> ``` Advanced variants exist for rarer cases: `$effect.pre` runs before DOM updates, `$effect.tracking()` reports whether code is running in a tracking context, `$effect.pending()` reports pending promises in the current boundary, and `$effect.root` creates a manually controlled effect scope.[^effect] -## Choosing a rune +## Choosing a Rune | Need | Use | | -------------------------------- | ---------- | | Component-local mutable state | `$state` | | Calculation from reactive inputs | `$derived` | | Component inputs | `$props` | | Browser side effects | `$effect` | -[^runes]: Svelte, “What are runes?”, Svelte documentation, https://svelte.dev/docs/svelte/what-are-runes - -[^state]: Svelte, “$state”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$state/llms.txt - -[^derived]: Svelte, “$derived”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$derived/llms.txt - -[^props]: Svelte, “$props”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$props/llms.txt - -[^effect]: Svelte, “$effect”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$effect/llms.txt +[^runes]: Svelte, “What are runes?”, Svelte documentation, <https://svelte.dev/docs/svelte/what-are-runes> +[^state]: Svelte, "\$state, Svelte documentation, <https://svelte.dev/docs/svelte/$state/> +[^derived]: Svelte, "\$derived, Svelte documentation, <https://svelte.dev/docs/svelte/$derived/> +[^props]: Svelte, "\$props, Svelte documentation, <https://svelte.dev/docs/svelte/$props/> +[^effect]: Svelte, "\$effect, Svelte documentation, <https://svelte.dev/docs/svelte/$effect/> - State
Show diff
diff --git a/src/content/docs/engineering/web/svelte/state.md b/src/content/docs/engineering/web/svelte/state.md index 0f641d9..372ef88 100644 --- a/src/content/docs/engineering/web/svelte/state.md +++ b/src/content/docs/engineering/web/svelte/state.md @@ -10,108 +10,121 @@ SvelteKit state management is mostly about where state should live in an app tha A browser is stateful, but a server process can be long-lived and shared by many users. A top-level variable in a server module is shared by everyone who hits that server process, and can also disappear when the process restarts. SvelteKit's state management docs use this as the core warning: do not store per-user data in shared server variables.[^kit-state] Do this instead: - authenticate users with cookies - persist durable user data in a database - return request-specific data from `load` - pass that data through props, context, or `$app/state` ### Keep `load` pure -Do not write to stores, globals, or other shared state inside `load`. Return data from -`load` and let SvelteKit pass it to the page. This keeps SSR safe and makes the app easier -to reason about.[^kit-state] +Do not write to stores, globals, or other shared state inside `load`. + +Return data from `load` and let SvelteKit pass it to the page. + +This keeps SSR safe and makes the app easier to reason about.[^kit-state] ```ts export async function load({ fetch }) { const response = await fetch("/api/user"); return { user: await response.json() }; } ``` ### Use context for app-level state -SvelteKit's own app state uses Svelte context on the server so that state is attached to -the component tree instead of a process-global singleton. You can use the same pattern for -your own state. Pass a function through context to preserve reactivity across boundaries:[^kit-state] +SvelteKit's own app state uses Svelte context on the server so that state is +attached to the component tree instead of a process-global singleton. You can +use the same pattern for your own state. Pass a function through context to +preserve reactivity across boundaries:[^kit-state] ```svelte <!-- src/routes/+layout.svelte --> <script> import { setContext } from 'svelte'; let { data } = $props(); setContext('user', () => data.user); </script> ``` ```svelte <!-- src/routes/user/+page.svelte --> <script> import { getContext } from 'svelte'; const user = getContext('user'); </script> <p>Welcome {user().name}</p> ``` -Prefer passing state down. During SSR, updating context state from a deeper component cannot -change markup that a parent has already rendered; on the client, the parent can react to the -new value, which can cause hydration flashes.[^kit-state] +Prefer passing state down. During SSR, updating context state from a deeper +component cannot change markup that a parent has already rendered; +on the client, the parent can react to the new value, which can cause hydration +flashes.[^kit-state] ### Page and layout components are reused -SvelteKit preserves layout and page component instances across navigation. That means setup -code in a component does not rerun just because `data` changed, and `onMount`/`onDestroy` do -not rerun on every route change. Values derived from `data` must be reactive:[^kit-state] +SvelteKit preserves layout and page component instances across navigation. + +That means setup code in a component does not rerun just because `data` changed, +and `onMount`/`onDestroy` do not rerun on every route change. + +Values derived from `data` must be reactive:[^kit-state] ```svelte <script> let { data } = $props(); let wordCount = $derived(data.content.split(' ').length); let estimatedReadingTime = $derived(wordCount / 250); </script> ``` If a component must be destroyed and recreated on navigation, key it by URL: ```svelte <script> import { page } from '$app/state'; </script> {#key page.url.pathname} <BlogPost title={data.title} content={data.content} /> {/key} ``` ### Put durable navigation state in the URL -If state should survive reloads or affect SSR, put it in the URL. Filters, sorting, tabs, -and pagination often belong in search params like `?sort=price&order=ascending`. Read them -in `load` through the `url` parameter or in components through `page.url.searchParams`.[^kit-state] +If state should survive reloads or affect SSR, put it in the URL. +Filters, sorting, tabs, and pagination often belong in search params like +`?sort=price&order=ascending`. + +Read them in `load` through the `url` parameter or in components through `page.url.searchParams`.[^kit-state] -For disposable UI state that should survive back/forward navigation without becoming URL or -database state, use SvelteKit snapshots.[^kit-state] +For disposable UI state that should survive back/forward navigation without +becoming URL or database state, use SvelteKit snapshots.[^kit-state] ## Choosing where state belongs | State kind | Put it here | | --------------------------------- | ------------------------------------- | | Durable user data | database, keyed by authenticated user | | Request-specific server data | `load` return values | | App tree state during SSR | Svelte context or `$app/state` | | URL-affecting state | URL search params | | Disposable history-entry UI state | SvelteKit snapshots | -For component-local state, derived values, component props, and browser effects, use Svelte 5 runes like `$state`, `$derived`, `$props`, and `$effect`; see [Runes](/engineering/web/svelte/runes/). +For component-local state, derived values, component props, and browser effects, +use Svelte 5 runes like `$state`, `$derived`, `$props`, and `$effect`; +see [Runes](/engineering/web/svelte/runes/). + +For small interactive widgets inside Astro pages, see [Svelte Islands in Astro](/engineering/web/svelte/islands/). -[^kit-state]: SvelteKit, “State management”, SvelteKit documentation LLM text, https://svelte.dev/docs/kit/state-management/llms.txt +[^kit-state]: SvelteKit, “State management”, SvelteKit documentation, <https://svelte.dev/docs/kit/state-management/> - Testing
Show diff
diff --git a/src/content/docs/engineering/web/svelte/testing.md b/src/content/docs/engineering/web/svelte/testing.md index 036882b..7cdf5e0 100644 --- a/src/content/docs/engineering/web/svelte/testing.md +++ b/src/content/docs/engineering/web/svelte/testing.md @@ -139,22 +139,19 @@ export default config; Keep E2E coverage small but meaningful: one critical happy path, one important failure path, and any flow that would be expensive to catch with isolated tests. ## Checklist - Test stable behavior and contracts, not Svelte internals. - Extract logic before reaching for component tests. - Use accessible queries where possible. - Await user interactions. - Use `flushSync` only when synchronous assertions need it. - Use browser-mode tests when browser reality matters. - Use real web primitives in server tests. - Keep at least one E2E test for the core user journey. -[^svelte-faq]: Svelte, “How do I test Svelte apps?”, Svelte FAQ, https://svelte.dev/docs/svelte/faq#How-do-I-test-Svelte-apps - -[^svelte-testing]: Svelte, “Testing”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/testing/llms.txt - -[^sveltest-site]: Scott Spence, “Sveltest - Comprehensive Testing Suite for Svelte”, https://sveltest.dev/ - -[^sveltest-readme]: Scott Spence, “Sveltest”, GitHub repository README, https://github.com/spences10/sveltest +[^svelte-faq]: Svelte, “How do I test Svelte apps?”, Svelte FAQ, <https://svelte.dev/docs/svelte/faq#How-do-I-test-Svelte-apps> +[^svelte-testing]: Svelte, “Testing”, Svelte documentation LLM text, <https://svelte.dev/docs/svelte/testing/> +[^sveltest-site]: Scott Spence, “Sveltest - Comprehensive Testing Suite for Svelte”, <https://sveltest.dev/> +[^sveltest-readme]: Scott Spence, “Sveltest”, GitHub repository README, <https://github.com/spences10/sveltest>
add a ToC
clean-up file paths
Moved / renamed
- Book Ahrens 2017 from Book Ahrens 2017
tag system/model
Updated
- Advanced
Show diff
diff --git a/src/content/docs/culture/baseball/advanced.md b/src/content/docs/culture/baseball/advanced.md index 18b521b..d1e0951 100644 --- a/src/content/docs/culture/baseball/advanced.md +++ b/src/content/docs/culture/baseball/advanced.md @@ -1,17 +1,20 @@ --- title: Advanced Stats +tags: + - baseball + - statistics --- ## WAR (Wins Above Replacement) There are **different WARs** (FanGraphs fWAR, Baseball-Reference bWAR, Baseball Prospectus WARP). ### Position players (FanGraphs) FanGraphs defines WAR as: ([Sabermetrics Library][1]) > **WAR = (Batting Runs + BaseRunning Runs + Fielding Runs + Positional Adjustment + League Adjustment + Replacement Runs) / RunsPerWin** Where (all in "runs"): - **Batting Runs** = `wRAA` (weighted runs above average, from wOBA - see below) - Information Civics
Show diff
diff --git a/src/content/docs/engineering/atproto/information-civics.md b/src/content/docs/engineering/atproto/information-civics.md index e3160c4..fc4f702 100644 --- a/src/content/docs/engineering/atproto/information-civics.md +++ b/src/content/docs/engineering/atproto/information-civics.md @@ -1,17 +1,21 @@ --- title: Information Civics +tags: + - atproto + - governance + - internet --- > Archived from [infocivics.com](https://web.archive.org/web/20200218214112/https://infocivics.com/) on February 18, 2020. Original essay by Paul Frazee. # Deconstructing the power structures of large-scale social computing networks ## I. Introduction How should the Internet be governed? How should we manage the information, media, software, politics, and communities of the Web? Though early crypto-anarchists imagined the Internet as ungovernable, anarchy does not describe the Internet we know today. Corporations oversee the majority of our online activity, with most people publishing and connecting through centralized platforms like Facebook, Twitter, and Google. - Dart
Show diff
diff --git a/src/content/docs/engineering/flutter/dart.md b/src/content/docs/engineering/flutter/dart.md index 02a88fe..0cd7116 100644 --- a/src/content/docs/engineering/flutter/dart.md +++ b/src/content/docs/engineering/flutter/dart.md @@ -1,17 +1,21 @@ --- title: Dart +tags: + - dart + - flutter + - programming --- Dart is a typed, object-oriented language used for Flutter, command-line tools, servers, and web apps. It feels familiar if you know JavaScript, Java, C#, Kotlin, or Swift, with classes, generics, async primitives, lexical closures, and package imports all part of the core language. Every Dart program starts at `main`. ```dart void main() { print('Hello, Dart'); } ``` - Ripgrep
Show diff
diff --git a/src/content/docs/engineering/general/ripgrep.md b/src/content/docs/engineering/general/ripgrep.md index dc4299b..4e7b6d4 100644 --- a/src/content/docs/engineering/general/ripgrep.md +++ b/src/content/docs/engineering/general/ripgrep.md @@ -1,17 +1,21 @@ --- title: Ripgrep +tags: + - cli + - search + - tools --- Ripgrep is a line-oriented search tool that recursively searches directories for regex patterns[^1]. It's designed for speed and respects .gitignore rules when searching within git repositories. ## Case Sensitivity Ripgrep supports three case sensitivity modes: Smart Case (`--smart-case`) is case-insensitive unless the pattern contains uppercase letters. Pattern `hello` matches "hello", "Hello", "HELLO" while pattern `Hello` only matches "Hello". Case Insensitive (`--ignore-case` or `-i`) is always case-insensitive regardless of pattern. Pattern `Hello` matches "hello", "Hello", "HELLO". - Submodules
Show diff
diff --git a/src/content/docs/engineering/git/submodules.md b/src/content/docs/engineering/git/submodules.md index cac2a8f..6f66547 100644 --- a/src/content/docs/engineering/git/submodules.md +++ b/src/content/docs/engineering/git/submodules.md @@ -1,17 +1,20 @@ --- title: Git Submodules Workflow +tags: + - git + - workflow --- ## Create or Add a Submodule ### Option A — Add an existing remote repo ```sh cd parent-repo git submodule add https://github.com/username/child-repo.git path/to/child-repo git submodule update --init --recursive ``` ### Option B — Add a local repo as a submodule (no remote) ```sh - Runes
Show diff
diff --git a/src/content/docs/engineering/web/svelte/runes.md b/src/content/docs/engineering/web/svelte/runes.md index 39d0487..6b741cd 100644 --- a/src/content/docs/engineering/web/svelte/runes.md +++ b/src/content/docs/engineering/web/svelte/runes.md @@ -1,17 +1,21 @@ --- title: Runes +tags: + - frontend + - reactivity + - svelte --- Svelte 5 uses runes for explicit component reactivity. This page covers the core state-related runes: `$state`, `$derived`, `$props`, and `$effect`. For SvelteKit server/client state placement, see [Svelte State Management](/engineering/web/svelte/state/). ## What runes are Runes are Svelte 5 syntax that controls the compiler. They begin with `$`, look like function calls, and do not need imports. They are not normal JavaScript values: you cannot assign them to variables or pass them as arguments, and the compiler only allows them in valid positions.[^runes] ```svelte <script> let message = $state('hello'); </script> ``` - Testing
Show diff
diff --git a/src/content/docs/engineering/web/svelte/testing.md b/src/content/docs/engineering/web/svelte/testing.md index 2a9042e..036882b 100644 --- a/src/content/docs/engineering/web/svelte/testing.md +++ b/src/content/docs/engineering/web/svelte/testing.md @@ -1,17 +1,21 @@ --- title: Testing Svelte Projects +tags: + - frontend + - svelte + - testing --- This page provides an overview of testing strategies for Svelte applications, covering unit tests, component tests, browser component tests, server tests, and end-to-end tests. It emphasizes testing stable behavior and contracts rather than Svelte. Svelte testing works best as a small pyramid: extract logic into unit tests, mount components only when behavior needs a DOM, and keep a few end-to-end tests for production-like confidence. The Svelte FAQ describes the usual split as unit, component, and end-to-end tests, and notes that you do not need to test implementation details that Svelte itself already covers.[^svelte-faq] ## Unit tests Use unit tests for business logic, validation, data transformation, state helpers, and edge cases. If a component is hard to test, first ask whether too much logic lives inside the component. - Recursive Descent
Show diff
diff --git a/src/content/docs/programming/algorithms/recursive-descent.md b/src/content/docs/programming/algorithms/recursive-descent.md index 43221a3..c0cc1e4 100644 --- a/src/content/docs/programming/algorithms/recursive-descent.md +++ b/src/content/docs/programming/algorithms/recursive-descent.md @@ -1,17 +1,21 @@ --- title: Recursive descent parsing +tags: + - algorithms + - compilers + - parsing --- A *recursive descent parser* (RDP) is a **top-down** parser where each nonterminal of a context-free grammar is implemented as a (mutually) recursive procedure. It parses from left to right, expanding productions according to the grammar and the current lookahead token.[^1] For *predictive* recursive descent (no backtracking), the grammar is typically in the LL(1) family: the next production can be chosen using a fixed, small lookahead (often one token).[^3] Key consequences: - Parser structure mirrors the grammar, which makes RDP ideal for *handwritten* parsers and small DSLs.[^2] - Time complexity is linear in the input length for LL(1) grammars; it may blow up with naïve backtracking. ## Grammar Requirements and Complexity - Patterns
Show diff
diff --git a/src/content/docs/programming/c_cpp/patterns.md b/src/content/docs/programming/c_cpp/patterns.md index c353ed8..34415f5 100644 --- a/src/content/docs/programming/c_cpp/patterns.md +++ b/src/content/docs/programming/c_cpp/patterns.md @@ -1,17 +1,21 @@ --- title: C/C++ Patterns +tags: + - c-cpp + - programming + - systems-programming --- Source: <https://cs61.seas.harvard.edu/site/2025/Patterns/> ## Silence Intentional Unused Variables Compile warning-free, but make intentional omissions explicit. ```cpp void* m61_malloc(size_t sz, const char* file, int line) { (void) file, (void) line; // silence warnings return malloc(sz); } ``` - Command
Show diff
diff --git a/src/content/docs/programming/design/command.md b/src/content/docs/programming/design/command.md index 466c07e..390b5d9 100644 --- a/src/content/docs/programming/design/command.md +++ b/src/content/docs/programming/design/command.md @@ -1,17 +1,20 @@ --- title: Command Pattern +tags: + - design-patterns + - programming --- Notes from *Game Programming Patterns*[^1] > Encapsulate a request as an object, thereby letting users parameterize clients with different requests, > queue or log requests, and support undoable operations.[^2] Robert Nystrom’s simpler definition: > A command is a reified method call. > ("Reify" = make something real or tangible - i.e., turn an action into an object.) - Instead of *calling a method directly*, wrap the call in an **object**. - The object can be **stored**, **passed around**, **queued**, **serialized**, or **executed later**. - Functionally similar to a **callback**, **closure**, or **first-class function**, but in an OOP form. - Algo W
Show diff
diff --git a/src/content/docs/programming/functional_programming/algo-w.md b/src/content/docs/programming/functional_programming/algo-w.md index e3946b5..d647fbd 100644 --- a/src/content/docs/programming/functional_programming/algo-w.md +++ b/src/content/docs/programming/functional_programming/algo-w.md @@ -1,17 +1,21 @@ --- title: Algorithm W +tags: + - functional-programming + - programming + - type-systems --- Algorithm W is a **syntax-directed** way to *construct* proofs of these judgments and compute principal types. ([Wikipedia][^1]) Algorithm W takes an environment and an expression and returns: ```text W(Γ, e) = (S, τ) ``` meaning: under substitution `S`, `e` has monotype `τ` in environment `SΓ`. Core machinery: - **Fresh type variables**: `newvar()`. - Hindley Milner
Show diff
diff --git a/src/content/docs/programming/functional_programming/hindley_milner.md b/src/content/docs/programming/functional_programming/hindley_milner.md index 1ecbe5f..4d385f1 100644 --- a/src/content/docs/programming/functional_programming/hindley_milner.md +++ b/src/content/docs/programming/functional_programming/hindley_milner.md @@ -1,17 +1,21 @@ --- title: Hindley-Milner +tags: + - functional-programming + - programming + - type-systems --- Hindley–Milner is a type system for the λ-calculus with **parametric polymorphism**. It has two key properties: 1. It can infer types **without annotations**. 2. It computes a **principal type**: the most general type from which all other valid types follow by specialization. ([Wikipedia][^1]) ## HM Types We distinguish: ### Monotypes (τ) Monotypes (simple types) are built from: - Regex
Show diff
diff --git a/src/content/docs/programming/general/regex.md b/src/content/docs/programming/general/regex.md index dc800d1..bf62ff7 100644 --- a/src/content/docs/programming/general/regex.md +++ b/src/content/docs/programming/general/regex.md @@ -1,17 +1,21 @@ --- title: Regular Expressions (by Example) +tags: + - programming + - regex + - search --- A regular expression is a pattern for finding text. Different tools support different regex features, so the same pattern may need a different flag or regex engine depending on where it runs. Ripgrep examples in this note use [Rust's](/programming/rust/module-system/) `regex` crate by default. That engine is designed for predictable search time and deliberately leaves out features such as lookaround and backreferences.[^regex] For ripgrep-specific flags, output formats, and search behavior, see [ripgrep](/engineering/general/ripgrep/). ## Basics - Zig
Show diff
diff --git a/src/content/docs/programming/zig/index.md b/src/content/docs/programming/zig/index.md index b73f0e5..93066d3 100644 --- a/src/content/docs/programming/zig/index.md +++ b/src/content/docs/programming/zig/index.md @@ -1,17 +1,21 @@ --- title: Zig Programming Language +tags: + - programming + - systems-programming + - zig --- Zig is a modern systems programming language that emphasizes safety, performance, and interoperability. ## Imports ```zig const std = @import("std"); ``` `@import` loads another Zig module. `"std"` is Zig's standard library. The `const std = ...` binding gives the file a short name for it. ## Public declarations - Css
Show diff
diff --git a/src/content/docs/ux/css.md b/src/content/docs/ux/css.md index 14f627d..421ac38 100644 --- a/src/content/docs/ux/css.md +++ b/src/content/docs/ux/css.md @@ -1,17 +1,21 @@ --- title: Structuring CSS +tags: + - css + - frontend + - ux --- The goal, as Julia puts it, boring, legible CSS that stays easy to change[^ref], powered by semantic HTML and vanilla CSS. Tailwind's useful lesson is structure, not class names. We still need systems for: - reset - tokens - base styles - components - utilities - spacing ## Files - Book Ahrens 2017
Show diff
diff --git a/src/content/docs/writing/book-ahrens-2017.mdx b/src/content/docs/writing/book-ahrens-2017.mdx index c7b9210..7d946ca 100644 --- a/src/content/docs/writing/book-ahrens-2017.mdx +++ b/src/content/docs/writing/book-ahrens-2017.mdx @@ -1,17 +1,21 @@ --- title: How to Take Smart Notes +tags: + - books + - note-taking + - writing --- import Aside from "../../../components/Aside.astro"; Two-Slip boxes in one markdown file: note and reference - notes extend and relate to other notes, not in isolation (one note can exist in different contexts - basically, we can understand how different ideas[^1]) Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/writing/write_to_learn/) Life requires context switching, and notes with an index can help me pick up where I left off in the thought process. This is important for my work, as I am a knowledge worker Strip the workflow of everything that can be considered unimportant (I should probably stop using Notion for note taking - only as content management) The author advises that we always have the tools at hand - pen & paper (anything to capture with)
June 16, 2026
build: drop starlight
Updated
- Clients
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/clients.mdx b/src/content/docs/engineering/atproto/oauth/clients.mdx index c90566e..cedbf63 100644 --- a/src/content/docs/engineering/atproto/oauth/clients.mdx +++ b/src/content/docs/engineering/atproto/oauth/clients.mdx @@ -1,20 +1,20 @@ --- title: OAuth Clients and Metadata --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../../../components/Aside.astro"; AT Protocol replaces central app registration with published client metadata. A client identifies itself with a `client_id`, and that `client_id` is a URL. ```text https://app.example.com/oauth-client-metadata.json ``` The authorization server fetches this document during the authorization flow. This is what lets a new client work across many PDS and entryway implementations without first registering in each provider's dashboard.[^client-id-metadata] ## What Metadata Is For Client metadata answers operational questions: - Which redirect URIs may this client use? - Which scopes might it request? - Identity
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/identity.mdx b/src/content/docs/engineering/atproto/oauth/identity.mdx index ce30bae..a12e25f 100644 --- a/src/content/docs/engineering/atproto/oauth/identity.mdx +++ b/src/content/docs/engineering/atproto/oauth/identity.mdx @@ -1,20 +1,20 @@ --- title: OAuth Identity and Discovery --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../../../components/Aside.astro"; Identity is the part of AT Protocol OAuth that differs most from familiar "Sign in with X" systems. A client is not only asking whether a login succeeded. It is asking whether a specific authorization server is allowed to speak for a specific AT Protocol account. <Aside type="note" title="Rule of thumb"> Use handles for input and display. Use DIDs for account state. Use issuer URLs for authorization-server identity. </Aside> ## DID, Handle, PDS Three identifiers appear in the flow: | Identifier | Example | Stability | Use | | --- | --- | --- | --- | - Oauth
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/index.mdx b/src/content/docs/engineering/atproto/oauth/index.mdx index d57eee4..de4a859 100644 --- a/src/content/docs/engineering/atproto/oauth/index.mdx +++ b/src/content/docs/engineering/atproto/oauth/index.mdx @@ -1,20 +1,20 @@ --- title: AT Protocol OAuth --- -import { Aside } from "@astrojs/starlight/components"; +import Aside from "../../../../../components/Aside.astro"; OAuth is the account authorization system for AT Protocol clients. It lets an app obtain permission to call a user's Personal Data Server (PDS) without asking for the user's password. The unusual part is not OAuth itself. The unusual part is where OAuth runs. AT Protocol has many PDS hosts and can use separate authorization servers, sometimes called entryways. A client therefore begins by discovering authority. It cannot hard-code one login domain and call the result authentication. <Aside type="note" title="Working definition"> AT Protocol OAuth binds four things together: an account DID, the account's current PDS, an authorization-server issuer, and a DPoP key held by one client instance. - Tokens
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/tokens.mdx b/src/content/docs/engineering/atproto/oauth/tokens.mdx index ab418a1..de31f27 100644 --- a/src/content/docs/engineering/atproto/oauth/tokens.mdx +++ b/src/content/docs/engineering/atproto/oauth/tokens.mdx @@ -1,20 +1,20 @@ --- title: OAuth Tokens and Security --- -import { Aside } from "@astrojs/starlight/components"; +import Aside from "../../../../../components/Aside.astro"; After approval, the client receives tokens and granted scopes. The main security question changes at this point. The client is no longer proving that the user approved the request; it is proving that each API request comes from the same client instance that received the tokens. ## Scopes Every AT Protocol OAuth session includes the `atproto` scope. It marks the session as using the AT Protocol OAuth profile. Without it, the server should not grant access to AT Protocol PDS resources.[^atproto-oauth] A client that only needs account login can request only `atproto`. A client that needs to read or write PDS resources requests additional permissions. - Drf
Show diff
diff --git a/src/content/docs/engineering/web/drf.mdx b/src/content/docs/engineering/web/drf.mdx index 5c61a02..c397f1f 100644 --- a/src/content/docs/engineering/web/drf.mdx +++ b/src/content/docs/engineering/web/drf.mdx @@ -1,19 +1,19 @@ --- title: DRF | Django REST Framework --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../../components/Aside.astro"; The de-facto standard for building REST APIs with Django. Also known as *DRF*. ## Viewsets - A viewset[^1] is DRF's version of a controller (Rails style) ## Serializers <Aside type="note" title="Definition"> Serializers[^2] allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into JSON, XML or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data. - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index f17761f..9de01d9 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -1,19 +1,19 @@ --- title: How to Be Perfect --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; Written by the venerable Michael Schur, creator of Parks & Recreation and of course, The Good Place. --- - Morality is how we think we should behave on earth <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> --- - README
Show diff
diff --git a/src/content/docs/programming/data_structures/README.mdx b/src/content/docs/programming/data_structures/README.mdx index f4fb474..86deacf 100644 --- a/src/content/docs/programming/data_structures/README.mdx +++ b/src/content/docs/programming/data_structures/README.mdx @@ -1,21 +1,21 @@ --- title: On Data Structures sidebar: badge: text: Start variant: note --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../../components/Aside.astro"; - A data structure[^1] is any data that's represented with its operations/methods. - Often used to describe the way a collection of items is organized. - Basic operations are retrieval/reading, insertion, and deletion. - These are described by the interface of the data structure's abstract data type.[^2] - An abstract data type, abbreviated ADT, is a data type's spec in a language <Aside type="note"> See Virginia Tech's opendsa [site](https://opendsa-server.cs.vt.edu/home/books) for more books. </Aside> [^1]: 1.1. Data Structures and Algorithms — CS2 Software Design & Data Structures. https://opendsa-server.cs.vt.edu/OpenDSA/Books/CS2/html/IntroDSA.html#a-philosophy-of-data-structures. Accessed 10 May 2024. [^2]: 1.2. Abstract Data Types — CS3 Data Structures & Algorithms. https://opendsa-server.cs.vt.edu/OpenDSA/Books/CS3/html/ADT.html. Accessed 10 May 2024 - Done
Show diff
diff --git a/src/content/docs/psychology/done.mdx b/src/content/docs/psychology/done.mdx index 5d96bc0..0e4c71e 100644 --- a/src/content/docs/psychology/done.mdx +++ b/src/content/docs/psychology/done.mdx @@ -1,20 +1,20 @@ --- title: The Cult of Done Manifesto --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; Source[^1] <Aside type="note"> 1. There are three states of being. Not knowing, action and completion. 2. Accept that everything is a draft. It helps to get it done. 3. There is no editing stage. 4. Pretending you know what you’re doing is almost the same as knowing what you are doing, so just accept that you know what you’re doing even if you don’t and do it. 5. Banish procrastination. If you wait more than a week to get an idea done, abandon it. 6. The point of being done is not to finish but to get other things done. 7. Once you’re done you can throw it away. - Indestructible
Show diff
diff --git a/src/content/docs/psychology/indestructible.mdx b/src/content/docs/psychology/indestructible.mdx index 1156c78..d0ceb17 100644 --- a/src/content/docs/psychology/indestructible.mdx +++ b/src/content/docs/psychology/indestructible.mdx @@ -1,18 +1,18 @@ --- title: Indestructible --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; - Kafka defines[^1] the indestructible as the place at the bottom of every individual that keeps going whether they choose to or not. <Aside type="note" title="Quote"> The indestructible is one: it is each individual human being and, at the same time, it is common to all, hence the incomparably indivisible union that exists between human beings. </Aside> [^1]: Kafka, Franz, Roberto Calasso, Geoffrey Brock, and Michael Hofmann. The Zürau Aphorisms of Franz Kafka. 1st American ed. New York: Schocken Books, 2006. - Shoshin
Show diff
diff --git a/src/content/docs/psychology/shoshin.mdx b/src/content/docs/psychology/shoshin.mdx index dd65148..bd0fb62 100644 --- a/src/content/docs/psychology/shoshin.mdx +++ b/src/content/docs/psychology/shoshin.mdx @@ -1,20 +1,20 @@ --- title: Shoshin --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; Defined as having an attitude of openness and eagerness without pre-conceptions when studying at a subject at an advanced level, like a beginner would or should - The more you know about a subject, the more likely you are to be close minded about new information, i.e. intellectual hubris - Santiago Ramón y Cajal was maligned for saying that adults don't grow new neurons - Alfred Wegener said the Earth's crust is made up of shifting plates - Research is mounting that GMO's are safe[^1] (Anti-GMO folks are more likely to be out of date in their knowledge) - Humility makes us behave less brazenly and be more empathetic. - Combat this by "\[making\] the effort to explain a relevant issue or topic to yourself or someone else in detail, either out loud or in writing,"[^2] i.e. a sequential manner where you make an effort to fill in gaps. - Challenge your ideas (how am I wrong?) and acknowledge that confirmation bias exists - Submodality
Show diff
diff --git a/src/content/docs/psychology/submodality.mdx b/src/content/docs/psychology/submodality.mdx index 7cce35b..b464102 100644 --- a/src/content/docs/psychology/submodality.mdx +++ b/src/content/docs/psychology/submodality.mdx @@ -1,20 +1,20 @@ --- title: Submodalities --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; - A submodality[^1] is a distinction in how we re-experience a past event. - *Example*: Remembering a visual event in black and white vs. color[^2] - The submodalities we have a firm grasp on dramatically influence our emotions and experiences - Everyone has their own developed submodalities and they control our emotions. - A lack of submodalities means submodalities are not developed - Overdeveloped means past events are re-experienced clearly - Controlling emotions mean recontextualizing submodalities. Ask questions with a gentle curiousity. <Aside type="caution" title="On NLP"> Note that this comes from NLP (Neurolinguistic Programming not Natural Language Processing), which, as wikipedia[^3] and others[^4] - Why We Read
Show diff
diff --git a/src/content/docs/psychology/why-we-read.mdx b/src/content/docs/psychology/why-we-read.mdx index 1ba89d2..97e44ab 100644 --- a/src/content/docs/psychology/why-we-read.mdx +++ b/src/content/docs/psychology/why-we-read.mdx @@ -1,16 +1,17 @@ --- title: Why We Should Read --- -import { Aside, Card } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; +import Card from "../../../components/Card.astro"; <Aside type="note" title="By Dr. Ruth J. Simmons"> The purpose of reading is to help us find the inner temple. If we enforce reading, we enforce reflection.[^1] </Aside> (My interpretation) Reading helps us find peace within ourselves and find serenity. [^1]: BOOKSTORES: How to Read More Books in the Golden Age of Content_. Accessed October 5, 2022. https://www.youtube.com/watch?v=lIW5jBrrsS0. - Book Ahrens 2017
Show diff
diff --git a/src/content/docs/writing/book-ahrens-2017.mdx b/src/content/docs/writing/book-ahrens-2017.mdx index 33c104e..c7b9210 100644 --- a/src/content/docs/writing/book-ahrens-2017.mdx +++ b/src/content/docs/writing/book-ahrens-2017.mdx @@ -1,20 +1,20 @@ --- title: How to Take Smart Notes --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; Two-Slip boxes in one markdown file: note and reference - notes extend and relate to other notes, not in isolation (one note can exist in different contexts - basically, we can understand how different ideas[^1]) Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/writing/write_to_learn/) Life requires context switching, and notes with an index can help me pick up where I left off in the thought process. This is important for my work, as I am a knowledge worker Strip the workflow of everything that can be considered unimportant (I should probably stop using Notion for note taking - only as content management) The author advises that we always have the tools at hand - pen & paper (anything to capture with) A journal is a "graveyard for thoughts", the slip box should be for notes[^2] Asking yourself what you should learn is a useless question - it's easier to do things with a clear view of the destination - Diataxis
Show diff
diff --git a/src/content/docs/writing/diataxis.mdx b/src/content/docs/writing/diataxis.mdx index 0f61025..ce34699 100644 --- a/src/content/docs/writing/diataxis.mdx +++ b/src/content/docs/writing/diataxis.mdx @@ -1,20 +1,20 @@ --- title: Diátaxis Framework --- -import { Aside } from '@astrojs/starlight/components'; +import Aside from "../../../components/Aside.astro"; Made by [Daniel Procida](https://vurt.eu/). <Aside type="note" title="Foundations"> Diátaxis is based on the principle that documentation must serve the needs of its users. Knowing how to do that means understanding what the needs of users are.[^1] </Aside> - Documentation writers are **practitioners** in the domain of a skill[^2]. - A skill's **domain** is defined by a craft - A **craft** is the use of a tool or product, or an entire discipline or profession - **Action** - Practical knowledge, knowing how
June 9, 2026
docs: svelte notes
Added
Updated
- State
Show diff
diff --git a/src/content/docs/engineering/web/svelte/state.md b/src/content/docs/engineering/web/svelte/state.md index d473c00..0f641d9 100644 --- a/src/content/docs/engineering/web/svelte/state.md +++ b/src/content/docs/engineering/web/svelte/state.md @@ -1,333 +1,117 @@ --- -title: Svelte State Management +title: State Management --- -Svelte has two related state questions: - -1. where state should live in an app that spans server and client -2. how reactive state is expressed inside Svelte 5 components. - -SvelteKit's rule of thumb[^kit-state] is to keep server state request-scoped, -while Svelte 5's runes make component reactivity explicit.[^runes] +SvelteKit state management is mostly about where state should live in an app that spans server and client. Its rule of thumb[^kit-state] is to keep server state request-scoped and avoid shared module state for per-user data. For Svelte 5 component reactivity, see [Runes](/engineering/web/svelte/runes/). ## SvelteKit state rules ### Do not put user state in server module globals A browser is stateful, but a server process can be long-lived and shared by many users. A top-level variable in a server module is shared by everyone who hits that server process, and can also disappear when the process restarts. SvelteKit's state management docs use this as the core warning: do not store per-user data in shared server variables.[^kit-state] Do this instead: - authenticate users with cookies - persist durable user data in a database - return request-specific data from `load` - pass that data through props, context, or `$app/state` ### Keep `load` pure Do not write to stores, globals, or other shared state inside `load`. Return data from `load` and let SvelteKit pass it to the page. This keeps SSR safe and makes the app easier to reason about.[^kit-state] ```ts export async function load({ fetch }) { const response = await fetch("/api/user"); return { user: await response.json() }; } ``` ### Use context for app-level state SvelteKit's own app state uses Svelte context on the server so that state is attached to the component tree instead of a process-global singleton. You can use the same pattern for your own state. Pass a function through context to preserve reactivity across boundaries:[^kit-state] ```svelte <!-- src/routes/+layout.svelte --> <script> import { setContext } from 'svelte'; let { data } = $props(); setContext('user', () => data.user); </script> ``` ```svelte <!-- src/routes/user/+page.svelte --> <script> import { getContext } from 'svelte'; const user = getContext('user'); </script> <p>Welcome {user().name}</p> ``` Prefer passing state down. During SSR, updating context state from a deeper component cannot change markup that a parent has already rendered; on the client, the parent can react to the new value, which can cause hydration flashes.[^kit-state] ### Page and layout components are reused SvelteKit preserves layout and page component instances across navigation. That means setup code in a component does not rerun just because `data` changed, and `onMount`/`onDestroy` do not rerun on every route change. Values derived from `data` must be reactive:[^kit-state] ```svelte <script> let { data } = $props(); let wordCount = $derived(data.content.split(' ').length); let estimatedReadingTime = $derived(wordCount / 250); </script> ``` If a component must be destroyed and recreated on navigation, key it by URL: ```svelte <script> import { page } from '$app/state'; </script> {#key page.url.pathname} <BlogPost title={data.title} content={data.content} /> {/key} ``` ### Put durable navigation state in the URL If state should survive reloads or affect SSR, put it in the URL. Filters, sorting, tabs, and pagination often belong in search params like `?sort=price&order=ascending`. Read them in `load` through the `url` parameter or in components through `page.url.searchParams`.[^kit-state] For disposable UI state that should survive back/forward navigation without becoming URL or database state, use SvelteKit snapshots.[^kit-state] -## What runes are - -Runes are Svelte 5 syntax that controls the compiler. They begin with `$`, look like function -calls, and do not need imports. They are not normal JavaScript values: you cannot assign them -to variables or pass them as arguments, and the compiler only allows them in valid positions.[^runes] - -```svelte -<script> - let message = $state('hello'); -</script> -``` - -## `$state` - -`$state` creates reactive state. The variable behaves like the value itself rather than like a -store object or setter API:[^state] - -```svelte -<script> - let count = $state(0); -</script> - -<button onclick={() => count++}> - clicks: {count} -</button> -``` - -When `$state` wraps an array or plain object, Svelte creates a deeply reactive proxy. -Mutating a nested property or calling an array method such as `push` triggers granular updates -for the parts of the UI that read that property.[^state] - -```svelte -<script> - let todos = $state([{ done: false, text: 'learn runes' }]); -</script> - -<button onclick={() => (todos[0].done = !todos[0].done)}> - {todos[0].done ? 'done' : 'not done'} -</button> -``` - -Important details: - -- Destructuring a reactive value gives you ordinary JavaScript references, not live reactive references.[^state] -- Class instances are not proxied, but class fields can use `$state`.[^state] -- Use reactive built-ins from `svelte/reactivity` for reactive `Set`, `Map`, `Date`, and `URL`.[^state] -- Use `$state.raw` for large objects or arrays that should only update by reassignment, not deep mutation.[^state] -- Use `$state.snapshot` when passing a non-proxy copy to APIs or libraries.[^state] -- Use `$state.eager` sparingly for immediate visual feedback during synchronized `await` updates.[^state] - -## `$derived` - -`$derived` creates reactive values from other reactive values. Component setup code runs once, so derived expressions are how you keep calculations in sync with changing state or props.[^derived] - -```svelte -<script> - let count = $state(0); - let doubled = $derived(count * 2); -</script> - -<button onclick={() => count++}> - {count} doubled is {doubled} -</button> -``` - -A `$derived` expression should be free of side effects. Svelte disallows state changes such as `count++` inside derived expressions.[^derived] - -For multi-line calculations, use `$derived.by`: - -```svelte -<script> - let numbers = $state([1, 2, 3]); - - let total = $derived.by(() => { - let sum = 0; - for (const n of numbers) sum += n; - return sum; - }); -</script> -``` - -Svelte tracks values read synchronously inside the derived expression or function body. Derived values are recalculated lazily when next read, and downstream updates are skipped if the derived value is referentially unchanged.[^derived] - -Deriveds can also be temporarily reassigned, which is useful for optimistic UI:[^derived] - -```svelte -<script> - let { post, like } = $props(); - let likes = $derived(post.likes); - - async function onclick() { - likes += 1; - - try { - await like(); - } catch { - likes -= 1; - } - } -</script> - -<button {onclick}>🧡 {likes}</button> -``` - -## `$props` - -`$props` reads component inputs. Most components destructure the returned props object:[^props] - -```svelte -<script> - let { adjective = 'happy' } = $props(); -</script> - -<p>This component is {adjective}</p> -``` - -Destructuring also supports renaming invalid identifiers, rest props, and TypeScript annotations:[^props] - -```svelte -<script lang="ts"> - interface Props { - adjective: string; - disabled?: boolean; - } - - let { adjective, disabled = false }: Props = $props(); -</script> -``` - -Props update when the parent updates. A child can temporarily reassign a prop value for local ephemeral state, but it should not mutate props it does not own unless the prop is explicitly bindable. Mutating a reactive proxy passed from a parent can update the UI but causes an ownership warning.[^props] - -For accessible form fields and labels, `$props.id()` creates an ID unique to the component instance and stable across SSR hydration.[^props] - -```svelte -<script> - const uid = $props.id(); -</script> - -<label for="{uid}-email">Email</label> -<input id="{uid}-email" type="email" /> -``` - -## `$effect` - -`$effect` runs side-effecting code when reactive dependencies change. It runs in the browser, not during server-side rendering, after the component has mounted and after DOM updates have been applied.[^effect] - -Use it for browser effects: third-party libraries, canvas drawing, analytics, subscriptions, timers, or direct DOM work. - -```svelte -<script> - let size = $state(50); - let color = $state('#ff3e00'); - let canvas; - - $effect(() => { - const context = canvas.getContext('2d'); - context.clearRect(0, 0, canvas.width, canvas.height); - context.fillStyle = color; - context.fillRect(0, 0, size, size); - }); -</script> - -<canvas bind:this={canvas} width="100" height="100"></canvas> -``` - -Svelte tracks reactive values read synchronously inside the effect and reruns the effect when they change. Values read after an `await`, inside `setTimeout`, or in another asynchronous callback are not tracked.[^effect] - -An effect can return a teardown function. The teardown runs before the effect reruns and when the effect is destroyed:[^effect] - -```svelte -<script> - let count = $state(0); - let milliseconds = $state(1000); - - $effect(() => { - const interval = setInterval(() => { - count += 1; - }, milliseconds); - - return () => clearInterval(interval); - }); -</script> -``` - -Do not use `$effect` to synchronize state that can be expressed as derived state. Prefer this:[^effect] - -```svelte -<script> - let count = $state(0); - let doubled = $derived(count * 2); -</script> -``` - -Advanced variants exist for rarer cases: `$effect.pre` runs before DOM updates, -`$effect.tracking()` reports whether code is running in a tracking context, -`$effect.pending()` reports pending promises in the current boundary, and -`$effect.root` creates a manually controlled effect scope.[^effect] - ## Choosing where state belongs | State kind | Put it here | | --------------------------------- | ------------------------------------- | | Durable user data | database, keyed by authenticated user | | Request-specific server data | `load` return values | | App tree state during SSR | Svelte context or `$app/state` | | URL-affecting state | URL search params | | Disposable history-entry UI state | SvelteKit snapshots | -| Component-local mutable state | `$state` | -| Calculation from reactive inputs | `$derived` | -| Component inputs | `$props` | -| Browser side effects | `$effect` | -[^kit-state]: SvelteKit, “State management”, SvelteKit documentation LLM text, https://svelte.dev/docs/kit/state-management/llms.txt - -[^runes]: Svelte, “What are runes?”, Svelte documentation, https://svelte.dev/docs/svelte/what-are-runes - -[^state]: Svelte, “$state”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$state/llms.txt +For component-local state, derived values, component props, and browser effects, use Svelte 5 runes like `$state`, `$derived`, `$props`, and `$effect`; see [Runes](/engineering/web/svelte/runes/). -[^derived]: Svelte, “$derived”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$derived/llms.txt - -[^props]: Svelte, “$props”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$props/llms.txt - -[^effect]: Svelte, “$effect”, Svelte documentation LLM text, https://svelte.dev/docs/svelte/$effect/llms.txt +[^kit-state]: SvelteKit, “State management”, SvelteKit documentation LLM text, https://svelte.dev/docs/kit/state-management/llms.txt - Testing
Show diff
diff --git a/src/content/docs/engineering/web/svelte/testing.md b/src/content/docs/engineering/web/svelte/testing.md index aea0610..2a9042e 100644 --- a/src/content/docs/engineering/web/svelte/testing.md +++ b/src/content/docs/engineering/web/svelte/testing.md @@ -1,17 +1,17 @@ --- -title: Testing Svelte Applications +title: Testing Svelte Projects --- This page provides an overview of testing strategies for Svelte applications, covering unit tests, component tests, browser component tests, server tests, and end-to-end tests. It emphasizes testing stable behavior and contracts rather than Svelte. Svelte testing works best as a small pyramid: extract logic into unit tests, mount components only when behavior needs a DOM, and keep a few end-to-end tests for production-like confidence. The Svelte FAQ describes the usual split as unit, component, and end-to-end tests, and notes that you do not need to test implementation details that Svelte itself already covers.[^svelte-faq] ## Unit tests Use unit tests for business logic, validation, data transformation, state helpers, and edge cases. If a component is hard to test, first ask whether too much logic lives inside the component.
June 7, 2026
docs: add regex by example
Added
June 6, 2026
fix: links
Updated
- Books
Show diff
diff --git a/src/content/docs/books.md b/src/content/docs/books.md index 8cf6378..88050ee 100644 --- a/src/content/docs/books.md +++ b/src/content/docs/books.md @@ -1,12 +1,12 @@ --- title: Books sidebar: badge: text: Start Here variant: success --- Links to notes I've taken on books. -1. [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) -2. [How to Be Perfect](/garden/philosophy/book-schur-2023/) +1. [How to Take Smart Notes](/writing/book-ahrens-2017/) +2. [How to Be Perfect](/philosophy/book-schur-2023/) - Atproto
Show diff
diff --git a/src/content/docs/engineering/atproto/index.md b/src/content/docs/engineering/atproto/index.md index 3fa3ac3..dbb2383 100644 --- a/src/content/docs/engineering/atproto/index.md +++ b/src/content/docs/engineering/atproto/index.md @@ -28,92 +28,92 @@ The AT Protocol uses a layered architecture: └─────────────────────────────────────────────────┘ ``` ### Identity - **DIDs (Decentralized Identifiers)**: Persistent identifiers (e.g., `did:plc:abc123`) that remain stable across server migrations. - **Handles**: Human-readable names (e.g., `@alice.bsky.social`) that resolve to DIDs via DNS or HTTP. ### Personal Data Servers (PDS) Every user's data lives in a **Personal Data Server**. A PDS: - Stores the user's repository (a signed, Merkle-tree-based data structure). -- Handles [OAuth authentication and authorization](/garden/engineering/atproto/oauth/). +- Handles [OAuth authentication and authorization](/engineering/atproto/oauth/). - Syncs data to relays and indexers. ### Relay (BGS) Relays aggregate data from many PDSs into a unified firehose, enabling: - Efficient indexing for search and discovery. - Feed generators to access content across the network. ### App View An **App View** consumes the firehose and provides application-specific APIs. For example, the Bluesky app view provides the social networking experience. ## Data Model ### Repositories -A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/garden/engineering/atproto/mst/). +A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/engineering/atproto/mst/). -- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/garden/engineering/atproto/cbor/). +- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/engineering/atproto/cbor/). - **Collections**: Namespaced groups of records (e.g., `app.bsky.feed.post`). - **Commits**: Signed snapshots of the repository state. ### Lexicons **Lexicons** are JSON schemas that define: - Record types and their fields. - XRPC methods (HTTP-like RPC calls). - Subscriptions for real-time data. Example Lexicon ID: `app.bsky.feed.post` ### AT-URIs Records are addressed using **AT-URIs**: ```sh at://did:plc:abc123/app.bsky.feed.post/3jqw2f7 ``` Format: `at://<authority>/<collection>/<rkey>` ## Key Technologies | Component | Purpose | | ------------------------------------- | ----------------------------------------------- | -| [DAG-CBOR](/garden/engineering/atproto/cbor/) | Canonical binary serialization format | -| [MST](/garden/engineering/atproto/mst/) | Content-addressed, verifiable key-value storage | -| [CAR](/garden/engineering/atproto/car/) | Archive format for repository export/sync | +| [DAG-CBOR](/engineering/atproto/cbor/) | Canonical binary serialization format | +| [MST](/engineering/atproto/mst/) | Content-addressed, verifiable key-value storage | +| [CAR](/engineering/atproto/car/) | Archive format for repository export/sync | | CIDs | Content identifiers linking to any data block | | XRPC | HTTP-based RPC protocol for API calls | -| [OAuth](/garden/engineering/atproto/oauth/) | Client authorization and account authentication | +| [OAuth](/engineering/atproto/oauth/) | Client authorization and account authentication | ## Sync & Federation ### Repo Sync Repositories are synchronized using: -1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/garden/engineering/atproto/car/). +1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/engineering/atproto/car/). 2. **`com.atproto.sync.subscribeRepos`**: Real-time firehose of commits across the network. ### Event Stream The firehose emits events: - **Commit**: New or updated records. - **Handle**: Handle changes. - **Identity**: DID document updates. - **Tombstone**: Account deletions. ## References - Official protocol specifications covering identity, data, and networking layers. [AT Protocol Specification](https://atproto.com/specs) - Oauth
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/index.mdx b/src/content/docs/engineering/atproto/oauth/index.mdx index d04599a..d57eee4 100644 --- a/src/content/docs/engineering/atproto/oauth/index.mdx +++ b/src/content/docs/engineering/atproto/oauth/index.mdx @@ -76,25 +76,25 @@ pretend public clients can keep shared secrets.[^oauth21][^oauth-security] The flow is correct only if these statements hold at the end: | Binding | Question | | --------------- | ---------------------------------------------------------------------------- | | Account binding | Did the token response name the DID the client expected? | | Server binding | Is the authorization-server issuer authoritative for that DID's current PDS? | | Token binding | Are the tokens bound to the DPoP key for this client instance? | This invariant explains most of the protocol's ceremony. PAR protects the authorization request. PKCE protects the code exchange. DPoP protects token use. DID and issuer checks protect account authentication. ## Further Reading -1. [Clients and Metadata](/garden/engineering/atproto/oauth/clients/) -2. [Identity and Discovery](/garden/engineering/atproto/oauth/identity/) -3. [Authorization Flow](/garden/engineering/atproto/oauth/flow/) -4. [Tokens and Security](/garden/engineering/atproto/oauth/tokens/) +1. [Clients and Metadata](/engineering/atproto/oauth/clients/) +2. [Identity and Discovery](/engineering/atproto/oauth/identity/) +3. [Authorization Flow](/engineering/atproto/oauth/flow/) +4. [Tokens and Security](/engineering/atproto/oauth/tokens/) ## References [^atproto-oauth]: Bluesky/AT Protocol. ["OAuth"](https://atproto.com/specs/oauth). [^oauth21]: IETF OAuth Working Group. ["The OAuth 2.1 Authorization Framework"](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/). [^oauth-security]: Lodderstedt, Torsten, et al. [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://datatracker.ietf.org/doc/html/rfc9700). - Home
Show diff
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index bf126f1..71c42e9 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -11,16 +11,16 @@ new or finds some wisdom that resonates with them. Digital gardens fascinated me for a long time. I miss the days of stumbling upon the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos of digital gardens. -Also, take a look at my notes on [cultivating](/garden/writing/cultivation/) a garden. +Also, take a look at my notes on [cultivating](/writing/cultivation/) a garden. - Aristotle Problem
Show diff
diff --git a/src/content/docs/philosophy/aristotle-problem.md b/src/content/docs/philosophy/aristotle-problem.md index b618a75..42962bf 100644 --- a/src/content/docs/philosophy/aristotle-problem.md +++ b/src/content/docs/philosophy/aristotle-problem.md @@ -5,16 +5,16 @@ title: Aristotle's Problem Domain Aristotle's problem domain was trying to define[^1] what makes a person good: 1. What **qualities** they ought to have? 2. How much should they have? 3. Is everyone capable of having them? 4. How do we get them? 5. What does having them look like? - The end goal is happiness (eudaimonia/flourishing) - To do so we need virtues (things that make us good at being human) - We're born with potential to get virtues - And a natural aptitude towards some - We become virtuous by doing virtuous things (habitual) [^1]: Schur, Michael. How to Be Perfect: A Foolproof Guide to Making the Correct Moral Decision in Every Situation You Ever Encounter Anywhere on Earth, Forever. -First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/garden/philosophy/book-schur-2023/)) +First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/philosophy/book-schur-2023/)) - Bentham Scale
Show diff
diff --git a/src/content/docs/philosophy/bentham-scale.md b/src/content/docs/philosophy/bentham-scale.md index 6547092..dbda944 100644 --- a/src/content/docs/philosophy/bentham-scale.md +++ b/src/content/docs/philosophy/bentham-scale.md @@ -1,17 +1,17 @@ --- title: Bentham's Scale --- - Intensity - Duration - Certainty - Propinquity (how soon it will happen) - Fecundity (how much pleasure) - Purity ($\frac{Pleasure}{Pain}$) - Extent (how many people benefit) - If you're acting publicly, spread as much pleasure you can ## Backlinks -1. [How to Be Perfect](/garden/philosophy/book-schur-2023/) -2. [The Trolly Problem](/garden/philosophy/trolley-problem/) +1. [How to Be Perfect](/philosophy/book-schur-2023/) +2. [The Trolly Problem](/philosophy/trolley-problem/) - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index efa8dad..f17761f 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -12,57 +12,57 @@ Written by the venerable Michael Schur, creator of Parks & Recreation and of cou <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> --- Everything has an ethical undercurrent and everything we do affects somebody Failure in trying to do the right thing is inevitable - But trying means we care Virtue ethics - what makes a person good or bad? - - [Aristotle](/garden/philosophy/aristotle-problem/) wrestled with this + - [Aristotle](/philosophy/aristotle-problem/) wrestled with this Brilliant instructors and wise friends are very important The Golden mean/goldilocks rule is that there is a spectrum that is like a see saw for virtues. If we veer to far towards one extreme, the see saw becomes imbalanced. - *ex.* Mildness is the golden mean of anger - Very challenging to define An excess of a virtue can harm the people around you If we don't take stock of our virtues, we can find ourselves moving towards extremes and these aspects can "calcify." As you practice, it becomes effortless - Schur talks about how Steve Carrell & Amy Poehler were like that with their comedy The closer we get to a golden mean, the easier it is to find others. - Examples include kindness and generosity Religious zealots ignore cruelty as it is not a slight against god Knowledge is how we escape cruelty --- <Aside type="note" title="The Trolley Problem" icon='information'> Do you let the trolley kill five workers ahead of you or do you switch to the other track and let one worker die? - Read more here: [link](/garden/philosophy/trolley-problem/) + Read more here: [link](/philosophy/trolley-problem/) --- by Philippa Foot </Aside> ## Quotes <Aside type="note" title="Hope" icon="open-book"> With enough work, no one is doomed to be forever deprived of magnanimity or courage or any other desirable quality, the way I’m doomed to get lost every time I walk around a parking garage looking for my car.[^1] </Aside> --- - Heuristic
Show diff
diff --git a/src/content/docs/philosophy/heuristic.md b/src/content/docs/philosophy/heuristic.md index c515e78..f572033 100644 --- a/src/content/docs/philosophy/heuristic.md +++ b/src/content/docs/philosophy/heuristic.md @@ -1,10 +1,10 @@ --- title: Heuristic --- # Heuristic - Enter an input and get an output (philosophical algorithm or function). - Gives us a rule of thumb for a certain scenario,[^1] as a guideline for our behavior -[^1]: [How to Be Perfect](/garden/philosophy/book-schur-2023/) +[^1]: [How to Be Perfect](/philosophy/book-schur-2023/) - Trolley Problem
Show diff
diff --git a/src/content/docs/philosophy/trolley-problem.md b/src/content/docs/philosophy/trolley-problem.md index 9752185..b883c23 100644 --- a/src/content/docs/philosophy/trolley-problem.md +++ b/src/content/docs/philosophy/trolley-problem.md @@ -1,24 +1,24 @@ --- title: The Trolley Problem --- - The problems arise when circumstances change - What if we're at a station with the lever and don't have the same amount of information? - What if we know someone on the tracks? - What if we push someone over a bridge to slow down the train and save everyone on the tracks? - Utilitarianism - Branch of consequentialism (only thing that matters is results) - The best action is what makes people the most happy (greatest happiness principle) - Developed by British philosophers Bentham (wanted himself studied and preserved after death) and Mill (had a rough childhood -- [Bentham's Scale](/garden/philosophy/bentham-scale/) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) +- [Bentham's Scale](/philosophy/bentham-scale/) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) - Utilitarians believe all people's happiness matters equally - Correlation does not imply causation - Humans don't often know the consequences of their actions - Most human actions don't have all the information - before or after - Critiques of utilitarianism center on the wide differences between everybody's pleasure and pain - When our actions can cause pain and suffering as a result, utilitarianism fails to take into account our integrity - Advantage of utilitarianism is a straightforward distribution (those in need get the most) ## Source/Backlink -[How to Be Perfect](/garden/philosophy/book-schur-2023/) +[How to Be Perfect](/philosophy/book-schur-2023/) - Hindley Milner
Show diff
diff --git a/src/content/docs/programming/functional_programming/hindley_milner.md b/src/content/docs/programming/functional_programming/hindley_milner.md index 74ab16c..1ecbe5f 100644 --- a/src/content/docs/programming/functional_programming/hindley_milner.md +++ b/src/content/docs/programming/functional_programming/hindley_milner.md @@ -176,27 +176,27 @@ with Γ mapping variables to schemes. The important rules (up to `let`) are: - infer `Γ ⊢ e₁ : τ₁`, `Γ ⊢ e₂ : τ₂`, - assert `τ₁` must be `τ₂ -> β` for fresh `β`, - unify `τ₁` with `τ₂ -> β`, giving substitution `S`, - result type is `S β`. 4. **Let**: For `let x = e₁ in e₂`: - infer `Γ ⊢ e₁ : τ₁`, - generalize `τ₁` to `σ = Gen(Γ, τ₁)`, - infer `Γ, x:σ ⊢ e₂ : τ₂`, - result type is `τ₂`. ## Algorithm W -See [Algorithm W](/garden/programming/functional_programming/algo-w/) +See [Algorithm W](/programming/functional_programming/algo-w/) ## Further Reading 1. Bernstein, Max. “Damas-Hindley-Milner Inference Two Ways.” Max Bernstein, 15 Oct. 2024, <https://bernsteinbear.com/blog/type-inference/>. 2. Diehl, Stephen. "Hindley-Milner Inference" Write You a Haskell. <https://smunix.github.io/dev.stephendiehl.com/fun/006_hindley_milner.html>. 3. Tuhola, Henri. Hindley-Milner Type System/Algorithm W Study. <https://boxbase.org//entries/2018/mar/5/hindley-milner>. 4. Hazelden, Phil. A Reckless Introduction to Hindley-Milner Type Inference. <https://reasonableapproximation.net/2019/05/05/hindley-milner.html>. [^1]: <https://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system> "Hindley–Milner type system" [^2]: <https://www.cs.tufts.edu/~nr/cs257/archive/martin-odersky/hmx.pdf> "Type Inference with Constrained Types" [^3]: <https://people.eecs.berkeley.edu/~necula/Papers/DamasMilnerAlgoW.pdf> "Principal type-schemes for functional programs" - Autonomy In Work
Show diff
diff --git a/src/content/docs/writing/autonomy_in_work.md b/src/content/docs/writing/autonomy_in_work.md index 3e9eb08..f363106 100644 --- a/src/content/docs/writing/autonomy_in_work.md +++ b/src/content/docs/writing/autonomy_in_work.md @@ -1,9 +1,9 @@ --- title: Autonomy in Work --- This occurs when we are able to break down our work in to small chunks and steer it in a direction that is most interesting to us. This removes the need for us to use willpower to get things done.[^ref] -[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) - P. 138 +[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017/) - P. 138 - Book Ahrens 2017
Show diff
diff --git a/src/content/docs/writing/book-ahrens-2017.mdx b/src/content/docs/writing/book-ahrens-2017.mdx index a0b9f0e..33c104e 100644 --- a/src/content/docs/writing/book-ahrens-2017.mdx +++ b/src/content/docs/writing/book-ahrens-2017.mdx @@ -1,103 +1,103 @@ --- title: How to Take Smart Notes --- import { Aside } from '@astrojs/starlight/components'; Two-Slip boxes in one markdown file: note and reference - notes extend and relate to other notes, not in isolation (one note can exist in different contexts - basically, we can understand how different ideas[^1]) -Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/garden/writing/write_to_learn/) +Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/writing/write_to_learn/) Life requires context switching, and notes with an index can help me pick up where I left off in the thought process. This is important for my work, as I am a knowledge worker Strip the workflow of everything that can be considered unimportant (I should probably stop using Notion for note taking - only as content management) The author advises that we always have the tools at hand - pen & paper (anything to capture with) A journal is a "graveyard for thoughts", the slip box should be for notes[^2] Asking yourself what you should learn is a useless question - it's easier to do things with a clear view of the destination - Deliberate practice helps us become better at making this journey[^3] > Nothing counts other than writing. The main goal[^4] of notes is to convey the truth (publishable insight) Note types: Fleeting, Permanent, Project (-specific) In order to find a topic, you need to have studied a subject - This makes me think of an old interview of Alexisonfire, where George says to make music, you have to listen to music. > By focusing on what is interesting and keeping written track of *your own intellectual development*, > topics, questions and arguments will emerge from the material without force. Rewarding work starts the positive feedback loop - Writing provides the feedback portion (we're forced to assess if we're understanding the material) -[Mere Exposure Effect](/garden/writing/mere_exposure_effect/): If we do something a lot, we *think* we're good at it, even if we're not +[Mere Exposure Effect](/writing/mere_exposure_effect/): If we do something a lot, we *think* we're good at it, even if we're not Focused attention is not very long. New technology damages our ability to practice sustained attention (where we work on one thing at a time) Creativity requires keeping an open mind and being able to switch to a narrow, analytical approach Memo-ize memories - group in to bundles, rather than discrete facts "Mind Like Water" - get knowledge out of our short term memory Willpower is like muscles - requires rest and gets exhausted quickly but can be strengthened Hand writing facilitates understanding because it is slow - college students have to understand what they hear rather than copy it down Shorter, in your own words allows us to focus on patterns, frames, and categories of an excerpt Re-reading breeds familiarity, writing forces us to confront misunderstanding - Cramming is for short term retention, not for learning The brain prioritizes comfort and its own happiness (like ego in The Power of Now) - Writing was Richard Feynman's thinking process (think outside your brain) -Forgetting can sometimes be [done by our minds](/garden/writing/active_inhibition/) as a filter so we don't get flooded with memories and associations (think join models in SQL) +Forgetting can sometimes be [done by our minds](/writing/active_inhibition/) as a filter so we don't get flooded with memories and associations (think join models in SQL) Memory can be measured by storage and retrieval strength - Storage strength can't be improved Linking is key! - Keep an eye towards other notes and contexts such that you can build the matrix around things you're interested in -Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/garden/writing/feature_positive_effect/)) +Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/writing/feature_positive_effect/)) Remember that the slip-box is just a tool[^5] -[Worldly Wisdom](/garden/writing/worldly_wisdom/): hanging life experiences on mental models +[Worldly Wisdom](/writing/worldly_wisdom/): hanging life experiences on mental models Spaced repitition and active recall are important for information retention. One idea per permanent note - place limits so that they stay concise. - Structure (experiment) and restrictions (assess what is important) are necessary for creativity The brain prioritizes information that is recently acquired and with emotions attached to it Evolution works by trial & error, not planning[^6] -- [Motivation](/garden/writing/motivation_when_studying/) is relational (students must identify with and see the purpose of their work) - - And be [free](/garden/writing/autonomy_in_work/) +- [Motivation](/writing/motivation_when_studying/) is relational (students must identify with and see the purpose of their work) + - And be [free](/writing/autonomy_in_work/) Athletes are more motivated when they imagine the training it takes to win.[^7] Build new habits to replace old ones, don't force old habits away - - The [goal of learning](/garden/writing/goal_of_learning/) is to evolve + - The [goal of learning](/writing/goal_of_learning/) is to evolve ## My Routine/Takeaways Keep a pen & paper handy at all times (if anything, just to avoid opening your phone when in the middle of a book) Abandon the notion of making perfect notes. Do you think the multicolored shit people made in college is something that would have helped you? Why not just make art instead? When processing notes, open up the source with anything you've highlighted - *ex. the Kindle notes & highlights for this book* Many of my attitudes towards learning are not conducive to learning, but to accomplishing a very specific task. Turn the writing everything and thinking about process in to a hobby [^1]: Page 20 - Goal Of Learning
Show diff
diff --git a/src/content/docs/writing/goal_of_learning.md b/src/content/docs/writing/goal_of_learning.md index 23f92a8..9d651c7 100644 --- a/src/content/docs/writing/goal_of_learning.md +++ b/src/content/docs/writing/goal_of_learning.md @@ -1,9 +1,9 @@ --- title: Goal of Learning --- > The goal of learning is not to accumulate knowledge but about becoming a different person with a different way of thinking. The author is trying to say[^1] that we learn to grow, not collect. -[^1]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) +[^1]: [How to Take Smart Notes](/writing/book-ahrens-2017/) - Motivation When Studying
Show diff
diff --git a/src/content/docs/writing/motivation_when_studying.md b/src/content/docs/writing/motivation_when_studying.md index 9724a19..f635980 100644 --- a/src/content/docs/writing/motivation_when_studying.md +++ b/src/content/docs/writing/motivation_when_studying.md @@ -1,17 +1,17 @@ --- title: Motivation when Studying --- - Students fail when they are not motivated - When they don't see the meaning in their work[^1] - When they can't connect it to their goals[^2] - - When they lack [freedom](/garden/writing/autonomy_in_work/) + - When they lack [freedom](/writing/autonomy_in_work/) - Motivation comes best from enjoying your work - Turn the writing everything and thinking about process in to a hobby - The book says artists and scientists are essentially information hobbyists. - Think Rivers Cuomo [^1]: Balduf, Megan. “Underachievement Among College Students.” Journal of Advanced Academics 20, no. 2 (February 2009): 274–94. <https://doi.org/10.1177/1932202X0902000204>. [^2]: Glynn, Shawn M., Gita Taasoobshirazi, and Peggy Brickman. “Science Motivation Questionnaire: Construct Validation with Nonscience Majors.” *Journal of Research in Science Teaching* 46, no. 2 (February 2009): 127–46. <https://doi.org/10.1002/tea.20267>. - On Writing
Show diff
diff --git a/src/content/docs/writing/on_writing.md b/src/content/docs/writing/on_writing.md index f688740..24a8105 100644 --- a/src/content/docs/writing/on_writing.md +++ b/src/content/docs/writing/on_writing.md @@ -1,14 +1,14 @@ --- title: On Writing sidebar: order: 1 badge: text: Start variant: note --- This section has notes about topics related to writing stories and educational material. It includes information about creating a site like this, and the backbone of my notes, writing to learn and using a zettlekasten system. -Here's a seed: [On Cultivating a Digital Garden](/garden/writing/cultivation/) +Here's a seed: [On Cultivating a Digital Garden](/writing/cultivation/) - Write To Learn
Show diff
diff --git a/src/content/docs/writing/write_to_learn.md b/src/content/docs/writing/write_to_learn.md index 56cb71a..0b4303a 100644 --- a/src/content/docs/writing/write_to_learn.md +++ b/src/content/docs/writing/write_to_learn.md @@ -1,14 +1,14 @@ --- title: Write to Learn --- When you write as you learn, you create a tangible outcome out of what you've read.[^ref] I think what inhibits me is that I want everything to be perfect and pristine, when in reality it's the substance that matters. Notes can be messy and disorganized, so long as you understand what you're putting in your brain. - Write down *anything* you think is helpful to understanding or need to remember - When you process, then you can create perfection (the structure is important) -[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) +[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017/)
build: upgrade astro
Updated
- Books
Show diff
diff --git a/src/content/docs/books.md b/src/content/docs/books.md index 39758a6..8cf6378 100644 --- a/src/content/docs/books.md +++ b/src/content/docs/books.md @@ -1,12 +1,12 @@ --- title: Books sidebar: badge: text: Start Here variant: success --- Links to notes I've taken on books. -1. [How to Take Smart Notes](/writing/book-ahrens-2017) -2. [How to Be Perfect](/philosophy/book-schur-2023) +1. [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) +2. [How to Be Perfect](/garden/philosophy/book-schur-2023/) - Atproto
Show diff
diff --git a/src/content/docs/engineering/atproto/index.md b/src/content/docs/engineering/atproto/index.md index 41487f0..3fa3ac3 100644 --- a/src/content/docs/engineering/atproto/index.md +++ b/src/content/docs/engineering/atproto/index.md @@ -28,92 +28,92 @@ The AT Protocol uses a layered architecture: └─────────────────────────────────────────────────┘ ``` ### Identity - **DIDs (Decentralized Identifiers)**: Persistent identifiers (e.g., `did:plc:abc123`) that remain stable across server migrations. - **Handles**: Human-readable names (e.g., `@alice.bsky.social`) that resolve to DIDs via DNS or HTTP. ### Personal Data Servers (PDS) Every user's data lives in a **Personal Data Server**. A PDS: - Stores the user's repository (a signed, Merkle-tree-based data structure). -- Handles [OAuth authentication and authorization](/engineering/atproto/oauth). +- Handles [OAuth authentication and authorization](/garden/engineering/atproto/oauth/). - Syncs data to relays and indexers. ### Relay (BGS) Relays aggregate data from many PDSs into a unified firehose, enabling: - Efficient indexing for search and discovery. - Feed generators to access content across the network. ### App View An **App View** consumes the firehose and provides application-specific APIs. For example, the Bluesky app view provides the social networking experience. ## Data Model ### Repositories -A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/engineering/atproto/mst). +A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/garden/engineering/atproto/mst/). -- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/engineering/atproto/cbor). +- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/garden/engineering/atproto/cbor/). - **Collections**: Namespaced groups of records (e.g., `app.bsky.feed.post`). - **Commits**: Signed snapshots of the repository state. ### Lexicons **Lexicons** are JSON schemas that define: - Record types and their fields. - XRPC methods (HTTP-like RPC calls). - Subscriptions for real-time data. Example Lexicon ID: `app.bsky.feed.post` ### AT-URIs Records are addressed using **AT-URIs**: ```sh at://did:plc:abc123/app.bsky.feed.post/3jqw2f7 ``` Format: `at://<authority>/<collection>/<rkey>` ## Key Technologies | Component | Purpose | | ------------------------------------- | ----------------------------------------------- | -| [DAG-CBOR](/engineering/atproto/cbor) | Canonical binary serialization format | -| [MST](/engineering/atproto/mst) | Content-addressed, verifiable key-value storage | -| [CAR](/engineering/atproto/car) | Archive format for repository export/sync | +| [DAG-CBOR](/garden/engineering/atproto/cbor/) | Canonical binary serialization format | +| [MST](/garden/engineering/atproto/mst/) | Content-addressed, verifiable key-value storage | +| [CAR](/garden/engineering/atproto/car/) | Archive format for repository export/sync | | CIDs | Content identifiers linking to any data block | | XRPC | HTTP-based RPC protocol for API calls | -| [OAuth](/engineering/atproto/oauth) | Client authorization and account authentication | +| [OAuth](/garden/engineering/atproto/oauth/) | Client authorization and account authentication | ## Sync & Federation ### Repo Sync Repositories are synchronized using: -1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/engineering/atproto/car). +1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/garden/engineering/atproto/car/). 2. **`com.atproto.sync.subscribeRepos`**: Real-time firehose of commits across the network. ### Event Stream The firehose emits events: - **Commit**: New or updated records. - **Handle**: Handle changes. - **Identity**: DID document updates. - **Tombstone**: Account deletions. ## References - Official protocol specifications covering identity, data, and networking layers. [AT Protocol Specification](https://atproto.com/specs) - Oauth
Show diff
diff --git a/src/content/docs/engineering/atproto/oauth/index.mdx b/src/content/docs/engineering/atproto/oauth/index.mdx index 1c0454a..d04599a 100644 --- a/src/content/docs/engineering/atproto/oauth/index.mdx +++ b/src/content/docs/engineering/atproto/oauth/index.mdx @@ -76,25 +76,25 @@ pretend public clients can keep shared secrets.[^oauth21][^oauth-security] The flow is correct only if these statements hold at the end: | Binding | Question | | --------------- | ---------------------------------------------------------------------------- | | Account binding | Did the token response name the DID the client expected? | | Server binding | Is the authorization-server issuer authoritative for that DID's current PDS? | | Token binding | Are the tokens bound to the DPoP key for this client instance? | This invariant explains most of the protocol's ceremony. PAR protects the authorization request. PKCE protects the code exchange. DPoP protects token use. DID and issuer checks protect account authentication. ## Further Reading -1. [Clients and Metadata](/engineering/atproto/oauth/clients) -2. [Identity and Discovery](/engineering/atproto/oauth/identity) -3. [Authorization Flow](/engineering/atproto/oauth/flow) -4. [Tokens and Security](/engineering/atproto/oauth/tokens) +1. [Clients and Metadata](/garden/engineering/atproto/oauth/clients/) +2. [Identity and Discovery](/garden/engineering/atproto/oauth/identity/) +3. [Authorization Flow](/garden/engineering/atproto/oauth/flow/) +4. [Tokens and Security](/garden/engineering/atproto/oauth/tokens/) ## References [^atproto-oauth]: Bluesky/AT Protocol. ["OAuth"](https://atproto.com/specs/oauth). [^oauth21]: IETF OAuth Working Group. ["The OAuth 2.1 Authorization Framework"](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/). [^oauth-security]: Lodderstedt, Torsten, et al. [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://datatracker.ietf.org/doc/html/rfc9700). - Home
Show diff
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index ba37340..bf126f1 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -11,16 +11,16 @@ new or finds some wisdom that resonates with them. Digital gardens fascinated me for a long time. I miss the days of stumbling upon the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos of digital gardens. -Also, take a look at my notes on [cultivating](/writing/cultivation) a garden. +Also, take a look at my notes on [cultivating](/garden/writing/cultivation/) a garden. - Aristotle Problem
Show diff
diff --git a/src/content/docs/philosophy/aristotle-problem.md b/src/content/docs/philosophy/aristotle-problem.md index 1b58c8b..b618a75 100644 --- a/src/content/docs/philosophy/aristotle-problem.md +++ b/src/content/docs/philosophy/aristotle-problem.md @@ -5,16 +5,16 @@ title: Aristotle's Problem Domain Aristotle's problem domain was trying to define[^1] what makes a person good: 1. What **qualities** they ought to have? 2. How much should they have? 3. Is everyone capable of having them? 4. How do we get them? 5. What does having them look like? - The end goal is happiness (eudaimonia/flourishing) - To do so we need virtues (things that make us good at being human) - We're born with potential to get virtues - And a natural aptitude towards some - We become virtuous by doing virtuous things (habitual) [^1]: Schur, Michael. How to Be Perfect: A Foolproof Guide to Making the Correct Moral Decision in Every Situation You Ever Encounter Anywhere on Earth, Forever. -First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/philosophy/book-schur-2023)) +First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/garden/philosophy/book-schur-2023/)) - Bentham Scale
Show diff
diff --git a/src/content/docs/philosophy/bentham-scale.md b/src/content/docs/philosophy/bentham-scale.md index 896fe3a..6547092 100644 --- a/src/content/docs/philosophy/bentham-scale.md +++ b/src/content/docs/philosophy/bentham-scale.md @@ -1,17 +1,17 @@ --- title: Bentham's Scale --- - Intensity - Duration - Certainty - Propinquity (how soon it will happen) - Fecundity (how much pleasure) - Purity ($\frac{Pleasure}{Pain}$) - Extent (how many people benefit) - If you're acting publicly, spread as much pleasure you can ## Backlinks -1. [How to Be Perfect](/philosophy/book-schur-2023) -2. [The Trolly Problem](/philosophy/trolley-problem) +1. [How to Be Perfect](/garden/philosophy/book-schur-2023/) +2. [The Trolly Problem](/garden/philosophy/trolley-problem/) - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index 7ac570f..efa8dad 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -12,57 +12,57 @@ Written by the venerable Michael Schur, creator of Parks & Recreation and of cou <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> --- Everything has an ethical undercurrent and everything we do affects somebody Failure in trying to do the right thing is inevitable - But trying means we care Virtue ethics - what makes a person good or bad? - - [Aristotle](/philosophy/aristotle-problem) wrestled with this + - [Aristotle](/garden/philosophy/aristotle-problem/) wrestled with this Brilliant instructors and wise friends are very important The Golden mean/goldilocks rule is that there is a spectrum that is like a see saw for virtues. If we veer to far towards one extreme, the see saw becomes imbalanced. - *ex.* Mildness is the golden mean of anger - Very challenging to define An excess of a virtue can harm the people around you If we don't take stock of our virtues, we can find ourselves moving towards extremes and these aspects can "calcify." As you practice, it becomes effortless - Schur talks about how Steve Carrell & Amy Poehler were like that with their comedy The closer we get to a golden mean, the easier it is to find others. - Examples include kindness and generosity Religious zealots ignore cruelty as it is not a slight against god Knowledge is how we escape cruelty --- <Aside type="note" title="The Trolley Problem" icon='information'> Do you let the trolley kill five workers ahead of you or do you switch to the other track and let one worker die? - Read more here: [link](/philosophy/trolley-problem) + Read more here: [link](/garden/philosophy/trolley-problem/) --- by Philippa Foot </Aside> ## Quotes <Aside type="note" title="Hope" icon="open-book"> With enough work, no one is doomed to be forever deprived of magnanimity or courage or any other desirable quality, the way I’m doomed to get lost every time I walk around a parking garage looking for my car.[^1] </Aside> --- - Heuristic
Show diff
diff --git a/src/content/docs/philosophy/heuristic.md b/src/content/docs/philosophy/heuristic.md index 52e8d59..c515e78 100644 --- a/src/content/docs/philosophy/heuristic.md +++ b/src/content/docs/philosophy/heuristic.md @@ -1,10 +1,10 @@ --- title: Heuristic --- # Heuristic - Enter an input and get an output (philosophical algorithm or function). - Gives us a rule of thumb for a certain scenario,[^1] as a guideline for our behavior -[^1]: [How to Be Perfect](/philosophy/book-schur-2023) +[^1]: [How to Be Perfect](/garden/philosophy/book-schur-2023/) - Trolley Problem
Show diff
diff --git a/src/content/docs/philosophy/trolley-problem.md b/src/content/docs/philosophy/trolley-problem.md index e940eb5..9752185 100644 --- a/src/content/docs/philosophy/trolley-problem.md +++ b/src/content/docs/philosophy/trolley-problem.md @@ -1,24 +1,24 @@ --- title: The Trolley Problem --- - The problems arise when circumstances change - What if we're at a station with the lever and don't have the same amount of information? - What if we know someone on the tracks? - What if we push someone over a bridge to slow down the train and save everyone on the tracks? - Utilitarianism - Branch of consequentialism (only thing that matters is results) - The best action is what makes people the most happy (greatest happiness principle) - Developed by British philosophers Bentham (wanted himself studied and preserved after death) and Mill (had a rough childhood -- [Bentham's Scale](/philosophy/bentham-scale) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) +- [Bentham's Scale](/garden/philosophy/bentham-scale/) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) - Utilitarians believe all people's happiness matters equally - Correlation does not imply causation - Humans don't often know the consequences of their actions - Most human actions don't have all the information - before or after - Critiques of utilitarianism center on the wide differences between everybody's pleasure and pain - When our actions can cause pain and suffering as a result, utilitarianism fails to take into account our integrity - Advantage of utilitarianism is a straightforward distribution (those in need get the most) ## Source/Backlink -[How to Be Perfect](/philosophy/book-schur-2023) +[How to Be Perfect](/garden/philosophy/book-schur-2023/) - Hindley Milner
Show diff
diff --git a/src/content/docs/programming/functional_programming/hindley_milner.md b/src/content/docs/programming/functional_programming/hindley_milner.md index f3c9100..74ab16c 100644 --- a/src/content/docs/programming/functional_programming/hindley_milner.md +++ b/src/content/docs/programming/functional_programming/hindley_milner.md @@ -176,27 +176,27 @@ with Γ mapping variables to schemes. The important rules (up to `let`) are: - infer `Γ ⊢ e₁ : τ₁`, `Γ ⊢ e₂ : τ₂`, - assert `τ₁` must be `τ₂ -> β` for fresh `β`, - unify `τ₁` with `τ₂ -> β`, giving substitution `S`, - result type is `S β`. 4. **Let**: For `let x = e₁ in e₂`: - infer `Γ ⊢ e₁ : τ₁`, - generalize `τ₁` to `σ = Gen(Γ, τ₁)`, - infer `Γ, x:σ ⊢ e₂ : τ₂`, - result type is `τ₂`. ## Algorithm W -See [Algorithm W](/programming/functional_programming/algo-w) +See [Algorithm W](/garden/programming/functional_programming/algo-w/) ## Further Reading 1. Bernstein, Max. “Damas-Hindley-Milner Inference Two Ways.” Max Bernstein, 15 Oct. 2024, <https://bernsteinbear.com/blog/type-inference/>. 2. Diehl, Stephen. "Hindley-Milner Inference" Write You a Haskell. <https://smunix.github.io/dev.stephendiehl.com/fun/006_hindley_milner.html>. 3. Tuhola, Henri. Hindley-Milner Type System/Algorithm W Study. <https://boxbase.org//entries/2018/mar/5/hindley-milner>. 4. Hazelden, Phil. A Reckless Introduction to Hindley-Milner Type Inference. <https://reasonableapproximation.net/2019/05/05/hindley-milner.html>. [^1]: <https://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system> "Hindley–Milner type system" [^2]: <https://www.cs.tufts.edu/~nr/cs257/archive/martin-odersky/hmx.pdf> "Type Inference with Constrained Types" [^3]: <https://people.eecs.berkeley.edu/~necula/Papers/DamasMilnerAlgoW.pdf> "Principal type-schemes for functional programs" - Autonomy In Work
Show diff
diff --git a/src/content/docs/writing/autonomy_in_work.md b/src/content/docs/writing/autonomy_in_work.md index ea96df5..3e9eb08 100644 --- a/src/content/docs/writing/autonomy_in_work.md +++ b/src/content/docs/writing/autonomy_in_work.md @@ -1,9 +1,9 @@ --- title: Autonomy in Work --- This occurs when we are able to break down our work in to small chunks and steer it in a direction that is most interesting to us. This removes the need for us to use willpower to get things done.[^ref] -[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017) - P. 138 +[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) - P. 138 - Book Ahrens 2017
Show diff
diff --git a/src/content/docs/writing/book-ahrens-2017.mdx b/src/content/docs/writing/book-ahrens-2017.mdx index 19e6041..a0b9f0e 100644 --- a/src/content/docs/writing/book-ahrens-2017.mdx +++ b/src/content/docs/writing/book-ahrens-2017.mdx @@ -1,103 +1,103 @@ --- title: How to Take Smart Notes --- import { Aside } from '@astrojs/starlight/components'; Two-Slip boxes in one markdown file: note and reference - notes extend and relate to other notes, not in isolation (one note can exist in different contexts - basically, we can understand how different ideas[^1]) -Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/writing/write_to_learn) +Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/garden/writing/write_to_learn/) Life requires context switching, and notes with an index can help me pick up where I left off in the thought process. This is important for my work, as I am a knowledge worker Strip the workflow of everything that can be considered unimportant (I should probably stop using Notion for note taking - only as content management) The author advises that we always have the tools at hand - pen & paper (anything to capture with) A journal is a "graveyard for thoughts", the slip box should be for notes[^2] Asking yourself what you should learn is a useless question - it's easier to do things with a clear view of the destination - Deliberate practice helps us become better at making this journey[^3] > Nothing counts other than writing. The main goal[^4] of notes is to convey the truth (publishable insight) Note types: Fleeting, Permanent, Project (-specific) In order to find a topic, you need to have studied a subject - This makes me think of an old interview of Alexisonfire, where George says to make music, you have to listen to music. > By focusing on what is interesting and keeping written track of *your own intellectual development*, > topics, questions and arguments will emerge from the material without force. Rewarding work starts the positive feedback loop - Writing provides the feedback portion (we're forced to assess if we're understanding the material) -[Mere Exposure Effect](/writing/mere_exposure_effect): If we do something a lot, we *think* we're good at it, even if we're not +[Mere Exposure Effect](/garden/writing/mere_exposure_effect/): If we do something a lot, we *think* we're good at it, even if we're not Focused attention is not very long. New technology damages our ability to practice sustained attention (where we work on one thing at a time) Creativity requires keeping an open mind and being able to switch to a narrow, analytical approach Memo-ize memories - group in to bundles, rather than discrete facts "Mind Like Water" - get knowledge out of our short term memory Willpower is like muscles - requires rest and gets exhausted quickly but can be strengthened Hand writing facilitates understanding because it is slow - college students have to understand what they hear rather than copy it down Shorter, in your own words allows us to focus on patterns, frames, and categories of an excerpt Re-reading breeds familiarity, writing forces us to confront misunderstanding - Cramming is for short term retention, not for learning The brain prioritizes comfort and its own happiness (like ego in The Power of Now) - Writing was Richard Feynman's thinking process (think outside your brain) -Forgetting can sometimes be [done by our minds](/writing/active_inhibition) as a filter so we don't get flooded with memories and associations (think join models in SQL) +Forgetting can sometimes be [done by our minds](/garden/writing/active_inhibition/) as a filter so we don't get flooded with memories and associations (think join models in SQL) Memory can be measured by storage and retrieval strength - Storage strength can't be improved Linking is key! - Keep an eye towards other notes and contexts such that you can build the matrix around things you're interested in -Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/writing/feature_positive_effect)) +Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/garden/writing/feature_positive_effect/)) Remember that the slip-box is just a tool[^5] -[Worldly Wisdom](/writing/worldly_wisdom): hanging life experiences on mental models +[Worldly Wisdom](/garden/writing/worldly_wisdom/): hanging life experiences on mental models Spaced repitition and active recall are important for information retention. One idea per permanent note - place limits so that they stay concise. - Structure (experiment) and restrictions (assess what is important) are necessary for creativity The brain prioritizes information that is recently acquired and with emotions attached to it Evolution works by trial & error, not planning[^6] -- [Motivation](/writing/motivation_when_studying) is relational (students must identify with and see the purpose of their work) - - And be [free](/writing/autonomy_in_work) +- [Motivation](/garden/writing/motivation_when_studying/) is relational (students must identify with and see the purpose of their work) + - And be [free](/garden/writing/autonomy_in_work/) Athletes are more motivated when they imagine the training it takes to win.[^7] Build new habits to replace old ones, don't force old habits away - - The [goal of learning](/writing/goal_of_learning) is to evolve + - The [goal of learning](/garden/writing/goal_of_learning/) is to evolve ## My Routine/Takeaways Keep a pen & paper handy at all times (if anything, just to avoid opening your phone when in the middle of a book) Abandon the notion of making perfect notes. Do you think the multicolored shit people made in college is something that would have helped you? Why not just make art instead? When processing notes, open up the source with anything you've highlighted - *ex. the Kindle notes & highlights for this book* Many of my attitudes towards learning are not conducive to learning, but to accomplishing a very specific task. Turn the writing everything and thinking about process in to a hobby [^1]: Page 20 - Goal Of Learning
Show diff
diff --git a/src/content/docs/writing/goal_of_learning.md b/src/content/docs/writing/goal_of_learning.md index 3bb72e6..23f92a8 100644 --- a/src/content/docs/writing/goal_of_learning.md +++ b/src/content/docs/writing/goal_of_learning.md @@ -1,9 +1,9 @@ --- title: Goal of Learning --- > The goal of learning is not to accumulate knowledge but about becoming a different person with a different way of thinking. The author is trying to say[^1] that we learn to grow, not collect. -[^1]: [How to Take Smart Notes](/writing/book-ahrens-2017) +[^1]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/) - Motivation When Studying
Show diff
diff --git a/src/content/docs/writing/motivation_when_studying.md b/src/content/docs/writing/motivation_when_studying.md index 959a16b..9724a19 100644 --- a/src/content/docs/writing/motivation_when_studying.md +++ b/src/content/docs/writing/motivation_when_studying.md @@ -1,17 +1,17 @@ --- title: Motivation when Studying --- - Students fail when they are not motivated - When they don't see the meaning in their work[^1] - When they can't connect it to their goals[^2] - - When they lack [freedom](/writing/autonomy_in_work) + - When they lack [freedom](/garden/writing/autonomy_in_work/) - Motivation comes best from enjoying your work - Turn the writing everything and thinking about process in to a hobby - The book says artists and scientists are essentially information hobbyists. - Think Rivers Cuomo [^1]: Balduf, Megan. “Underachievement Among College Students.” Journal of Advanced Academics 20, no. 2 (February 2009): 274–94. <https://doi.org/10.1177/1932202X0902000204>. [^2]: Glynn, Shawn M., Gita Taasoobshirazi, and Peggy Brickman. “Science Motivation Questionnaire: Construct Validation with Nonscience Majors.” *Journal of Research in Science Teaching* 46, no. 2 (February 2009): 127–46. <https://doi.org/10.1002/tea.20267>. - On Writing
Show diff
diff --git a/src/content/docs/writing/on_writing.md b/src/content/docs/writing/on_writing.md index 86d07c0..f688740 100644 --- a/src/content/docs/writing/on_writing.md +++ b/src/content/docs/writing/on_writing.md @@ -1,14 +1,14 @@ --- title: On Writing sidebar: order: 1 badge: text: Start variant: note --- This section has notes about topics related to writing stories and educational material. It includes information about creating a site like this, and the backbone of my notes, writing to learn and using a zettlekasten system. -Here's a seed: [On Cultivating a Digital Garden](/writing/cultivation) +Here's a seed: [On Cultivating a Digital Garden](/garden/writing/cultivation/) - Write To Learn
Show diff
diff --git a/src/content/docs/writing/write_to_learn.md b/src/content/docs/writing/write_to_learn.md index 553b59e..56cb71a 100644 --- a/src/content/docs/writing/write_to_learn.md +++ b/src/content/docs/writing/write_to_learn.md @@ -1,14 +1,14 @@ --- title: Write to Learn --- When you write as you learn, you create a tangible outcome out of what you've read.[^ref] I think what inhibits me is that I want everything to be perfect and pristine, when in reality it's the substance that matters. Notes can be messy and disorganized, so long as you understand what you're putting in your brain. - Write down *anything* you think is helpful to understanding or need to remember - When you process, then you can create perfection (the structure is important) -[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017) +[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017/)
docs: lolmets
Added
June 4, 2026
June 2, 2026
fix: link
Updated
- Motivation When Studying
Show diff
diff --git a/src/content/docs/writing/motivation_when_studying.md b/src/content/docs/writing/motivation_when_studying.md index 3b1823c..959a16b 100644 --- a/src/content/docs/writing/motivation_when_studying.md +++ b/src/content/docs/writing/motivation_when_studying.md @@ -1,17 +1,17 @@ --- title: Motivation when Studying --- - Students fail when they are not motivated - When they don't see the meaning in their work[^1] - When they can't connect it to their goals[^2] - - When they lack [freedom](/writing/autonomy-in-work) + - When they lack [freedom](/writing/autonomy_in_work) - Motivation comes best from enjoying your work - Turn the writing everything and thinking about process in to a hobby - The book says artists and scientists are essentially information hobbyists. - Think Rivers Cuomo [^1]: Balduf, Megan. “Underachievement Among College Students.” Journal of Advanced Academics 20, no. 2 (February 2009): 274–94. <https://doi.org/10.1177/1932202X0902000204>. [^2]: Glynn, Shawn M., Gita Taasoobshirazi, and Peggy Brickman. “Science Motivation Questionnaire: Construct Validation with Nonscience Majors.” *Journal of Research in Science Teaching* 46, no. 2 (February 2009): 127–46. <https://doi.org/10.1002/tea.20267>.
docs: what we resist persists
Added
Updated
- Levenshtein Distance
Show diff
diff --git a/src/content/docs/programming/algorithms/levenshtein-distance.md b/src/content/docs/programming/algorithms/levenshtein-distance.md index 2df5023..d421e1d 100644 --- a/src/content/docs/programming/algorithms/levenshtein-distance.md +++ b/src/content/docs/programming/algorithms/levenshtein-distance.md @@ -24,54 +24,55 @@ Distance: `3` ## Dynamic Programming Let `d[i][j]` be the edit distance between: - the first `i` characters of string `a` - the first `j` characters of string `b` Base cases: ```text d[0][j] = j d[i][0] = i ``` Those mean an empty string needs `j` insertions to become a prefix of length -`j`, and a prefix of length `i` needs `i` deletions to become empty.[^1][^2] +`j`, and a prefix of length `i` needs `i` deletions to become empty.[^1] -Recurrence: +Recurrence[^2]: ```py cost = 0 if a[i - 1] == b[j - 1] else 1 d[i][j] = min( d[i - 1][j] + 1, # delete d[i][j - 1] + 1, # insert d[i - 1][j - 1] + cost # substitute or match ) ``` The answer is `d[len(a)][len(b)]`. ## Complexity For strings of length `m` and `n`: - time: `O(mn)` - memory: `O(mn)` with the full table - memory: `O(min(m, n))` if only the previous row is kept Use the full table when you need the edit script. Use row compression when you only need the distance. ## Use Case Levenshtein distance is useful for: - spell correction - fuzzy search - typo tolerance - approximate matching - comparing biological or symbolic sequences [^1]: V. I. Levenshtein, "Binary Codes Capable of Correcting Deletions, Insertions, and Reversals", 1966 English translation of the 1965 Russian paper. <https://nymity.ch/sybilhunting/pdf/Levenshtein1966a.pdf> + [^2]: Robert A. Wagner and Michael J. Fischer, "The String-to-String Correction Problem", Journal of the ACM, 1974. - Motivation When Studying
Show diff
diff --git a/src/content/docs/writing/motivation_when_studying.md b/src/content/docs/writing/motivation_when_studying.md index 74b4a14..3b1823c 100644 --- a/src/content/docs/writing/motivation_when_studying.md +++ b/src/content/docs/writing/motivation_when_studying.md @@ -1,16 +1,17 @@ --- title: Motivation when Studying --- - Students fail when they are not motivated - - When they don't see the meaning in their work[^1] - - When they can't connect it to their goals[^2] - - When they lack [[Autonomy in Work|freedom]] + - When they don't see the meaning in their work[^1] + - When they can't connect it to their goals[^2] + - When they lack [freedom](/writing/autonomy-in-work) - Motivation comes best from enjoying your work - - Turn the writing everything and thinking about process in to a hobby - - The book says artists and scientists are essentially information hobbyists. - - Think Rivers Cuomo + - Turn the writing everything and thinking about process in to a hobby + - The book says artists and scientists are essentially information hobbyists. + - Think Rivers Cuomo [^1]: Balduf, Megan. “Underachievement Among College Students.” Journal of Advanced Academics 20, no. 2 (February 2009): 274–94. <https://doi.org/10.1177/1932202X0902000204>. -[^2]: Glynn, Shawn M., Gita Taasoobshirazi, and Peggy Brickman. “Science Motivation Questionnaire: Construct Validation with Nonscience Majors.” _Journal of Research in Science Teaching_ 46, no. 2 (February 2009): 127–46. <https://doi.org/10.1002/tea.20267>. + +[^2]: Glynn, Shawn M., Gita Taasoobshirazi, and Peggy Brickman. “Science Motivation Questionnaire: Construct Validation with Nonscience Majors.” *Journal of Research in Science Teaching* 46, no. 2 (February 2009): 127–46. <https://doi.org/10.1002/tea.20267>.
June 1, 2026
docs: direnv note
Added
Updated
- Engineering
Show diff
diff --git a/src/content/docs/engineering/index.md b/src/content/docs/engineering/index.md index b528bd5..797ea1c 100644 --- a/src/content/docs/engineering/index.md +++ b/src/content/docs/engineering/index.md @@ -1,10 +1,6 @@ --- title: Engineering -sidebar: - badge: - text: Start - variant: note --- Notes on Software Engineering as an industry and various tools and practices that are used. - Home
Show diff
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index e885f8c..ba37340 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,17 +1,17 @@ --- -title: Owais' Places +title: Welcome description: desertthunder's digital garden homepage --- Hi! My name is Owais and this is my digital garden. It's a collection of notes I've taken on topics that interest me. This includes a lot of engineering and programming notes that I've taken (and continue to take) throughout my career and while working on personal projects. My hope is that someone learns something new or finds some wisdom that resonates with them. Digital gardens fascinated me for a long time. I miss the days of stumbling upon the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) on my computer, and [Astro](https://astro.build/) for publishing. - Programming
Show diff
diff --git a/src/content/docs/programming/index.md b/src/content/docs/programming/index.md index 4720e5f..e093a0d 100644 --- a/src/content/docs/programming/index.md +++ b/src/content/docs/programming/index.md @@ -1,30 +1,23 @@ --- title: On Programming -sidebar: - badge: - text: Start - variant: note - --- This will contain notes related to programming languages I've "learned" or am learning. Can you ever really know a programming language top to bottom unless you wrote it? ## Proficiencies +Updated June 2026 + - TypeScript - Python - Java - Ruby - Go - -## Languages to Learn - -As of May 2024, these are languages that are on my radar to learn: - -- C++ +- Dart - Elixir +- Gleam - Rust -- Elm - - or Gleam +- F# +- OCaml
May 31, 2026
docs: BEAM me up
Added
May 29, 2026
docs: add Levenshtein distance algorithm notes
Added
May 26, 2026
docs: atproto oauth spec notes
Updated
- Atproto
Show diff
diff --git a/src/content/docs/engineering/atproto/index.md b/src/content/docs/engineering/atproto/index.md index 1311215..41487f0 100644 --- a/src/content/docs/engineering/atproto/index.md +++ b/src/content/docs/engineering/atproto/index.md @@ -28,83 +28,84 @@ The AT Protocol uses a layered architecture: └─────────────────────────────────────────────────┘ ``` ### Identity - **DIDs (Decentralized Identifiers)**: Persistent identifiers (e.g., `did:plc:abc123`) that remain stable across server migrations. - **Handles**: Human-readable names (e.g., `@alice.bsky.social`) that resolve to DIDs via DNS or HTTP. ### Personal Data Servers (PDS) Every user's data lives in a **Personal Data Server**. A PDS: - Stores the user's repository (a signed, Merkle-tree-based data structure). -- Handles authentication and authorization. +- Handles [OAuth authentication and authorization](/engineering/atproto/oauth). - Syncs data to relays and indexers. ### Relay (BGS) Relays aggregate data from many PDSs into a unified firehose, enabling: - Efficient indexing for search and discovery. - Feed generators to access content across the network. ### App View An **App View** consumes the firehose and provides application-specific APIs. For example, the Bluesky app view provides the social networking experience. ## Data Model ### Repositories A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/engineering/atproto/mst). - **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/engineering/atproto/cbor). - **Collections**: Namespaced groups of records (e.g., `app.bsky.feed.post`). - **Commits**: Signed snapshots of the repository state. ### Lexicons **Lexicons** are JSON schemas that define: - Record types and their fields. - XRPC methods (HTTP-like RPC calls). - Subscriptions for real-time data. Example Lexicon ID: `app.bsky.feed.post` ### AT-URIs Records are addressed using **AT-URIs**: ```sh at://did:plc:abc123/app.bsky.feed.post/3jqw2f7 ``` Format: `at://<authority>/<collection>/<rkey>` ## Key Technologies -| Component | Purpose | -| -------------------------------------------- | ----------------------------------------------- | +| Component | Purpose | +| ------------------------------------- | ----------------------------------------------- | | [DAG-CBOR](/engineering/atproto/cbor) | Canonical binary serialization format | | [MST](/engineering/atproto/mst) | Content-addressed, verifiable key-value storage | | [CAR](/engineering/atproto/car) | Archive format for repository export/sync | -| CIDs | Content identifiers linking to any data block | -| XRPC | HTTP-based RPC protocol for API calls | +| CIDs | Content identifiers linking to any data block | +| XRPC | HTTP-based RPC protocol for API calls | +| [OAuth](/engineering/atproto/oauth) | Client authorization and account authentication | ## Sync & Federation ### Repo Sync Repositories are synchronized using: 1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/engineering/atproto/car). 2. **`com.atproto.sync.subscribeRepos`**: Real-time firehose of commits across the network. ### Event Stream The firehose emits events: - **Commit**: New or updated records.
May 25, 2026
refactor: migrate remaining mkdocs material directives to Asides from starlight
Added
Moved / renamed
- Indestructible from Indestructible
- Shoshin from Shoshin
- Diataxis from Diataxis
Removed
- Done
- Submodality
May 20, 2026
docs: strategy pattern
Added
May 17, 2026
feat: update description
Updated
- Home
Show diff
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 0d2eae4..e885f8c 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,40 +1,26 @@ --- -title: Desert Thunder's Digital Garden +title: Owais' Places description: desertthunder's digital garden homepage --- -import { Aside } from '@astrojs/starlight/components'; - -<Aside type="caution" title="Currently Remodeling 🚧"> - I've very recently migrated this site from `mkdocs` to `astro/starlight` - and am in the process of updating all of my notes. Please bear with me as - some admonitions/callouts will be broken. You'll see a lot of `!!! info`, - `!!! quote`, or `::: info`, `::: quote` etc. They'll be changed to be more - like this block. - - Some links will also be broken. -</Aside> - Hi! My name is Owais and this is my digital garden. It's a collection of notes I've taken on topics that interest me. This includes a lot of engineering and -programming notes that I've taken throughout my career and while working on -personal projects. My hope is that someone learns something new or finds some -wisdom that resonates with them. +programming notes that I've taken (and continue to take) throughout my career +and while working on personal projects. My hope is that someone learns something +new or finds some wisdom that resonates with them. -Digital gardens have been fascinating for me for a long time. I miss the days -of stumbling upon [information on an odd personal site](https://tilde.town/~dozens/sofa/) -on the internet and want to be a part of bringing that back. I've tried keeping -gardens in various iterations with tools like notion and even google drive, but -nothing has been quite as consistent as a combination of some plaintext editor -(VSCode & now Neovim) or -"[Knowledge IDE](https://dev.to/envoy_/obsidian-an-ide-for-your-brain-1bn7)" -like Obsidian. +Digital gardens fascinated me for a long time. I miss the days of stumbling upon +the [odd personal site](https://tilde.town/~dozens/sofa/) and want to be a part of +bringing that back. I've tried keeping gardens in various iterations with tools +like notion and even google drive, but nothing has been quite as consistent as a +combination of [Obsidian](https://obsidian.md/) on my phone, [Neovim](https://neovim.io/) +on my computer, and [Astro](https://astro.build/) for publishing. ## Inspiration -Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/). -After starting a new python project and activating my virtual environment, I -pretty much always install mkdocs with the material theme. That site, while also -having some fantastic information, reminded me that I can just use mkdocs. +Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/) +and the writing of [Maggie Appleton](https://maggieappleton.com/). She wrote a +phenomenal [essay](https://maggieappleton.com/garden-history) on the history & ethos +of digital gardens. Also, take a look at my notes on [cultivating](/writing/cultivation) a garden.
docs: structuring css
Added
May 16, 2026
docs: mirror info civics essay
Added
- Blockchain.png
- Centralization Graphs.png
- Committee Of Five Presenting The Declaration Of Independence To Congress.jpg
- Constitution.jpg
- Eth.png
- Gnu.png
- John Locke.jpg
- July Revolution.jpg
- King George Iii.jpg
- P2p.png
- Proposed Tag.png
- Pubkey.gif
- Putneydebates.jpg
- Separation Of Powers.jpg
- Statue Of Liberty.png
- Information Civics
- Patterns
May 11, 2026
docs: golden tests
Added
May 7, 2026
docs: di
docs: add constellation notes
Added
chore: adjust base url
Updated
- Books
Show diff
diff --git a/src/content/docs/books.md b/src/content/docs/books.md index 85fadc0..39758a6 100644 --- a/src/content/docs/books.md +++ b/src/content/docs/books.md @@ -1,12 +1,12 @@ --- title: Books sidebar: badge: text: Start Here variant: success --- Links to notes I've taken on books. -1. [How to Take Smart Notes](/garden/writing/book-ahrens-2017) -2. [How to Be Perfect](/garden/philosophy/book-schur-2023) +1. [How to Take Smart Notes](/writing/book-ahrens-2017) +2. [How to Be Perfect](/philosophy/book-schur-2023) - Atproto
Show diff
diff --git a/src/content/docs/engineering/atproto/index.md b/src/content/docs/engineering/atproto/index.md index 7e1e465..1311215 100644 --- a/src/content/docs/engineering/atproto/index.md +++ b/src/content/docs/engineering/atproto/index.md @@ -46,73 +46,73 @@ A PDS: ### Relay (BGS) Relays aggregate data from many PDSs into a unified firehose, enabling: - Efficient indexing for search and discovery. - Feed generators to access content across the network. ### App View An **App View** consumes the firehose and provides application-specific APIs. For example, the Bluesky app view provides the social networking experience. ## Data Model ### Repositories -A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/garden/engineering/atproto/mst). +A **repository** is a user's complete data store, structured as a [Merkle Search Tree (MST)](/engineering/atproto/mst). -- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/garden/engineering/atproto/cbor). +- **Records**: Individual data items (posts, likes, follows) stored as [DAG-CBOR](/engineering/atproto/cbor). - **Collections**: Namespaced groups of records (e.g., `app.bsky.feed.post`). - **Commits**: Signed snapshots of the repository state. ### Lexicons **Lexicons** are JSON schemas that define: - Record types and their fields. - XRPC methods (HTTP-like RPC calls). - Subscriptions for real-time data. Example Lexicon ID: `app.bsky.feed.post` ### AT-URIs Records are addressed using **AT-URIs**: ```sh at://did:plc:abc123/app.bsky.feed.post/3jqw2f7 ``` Format: `at://<authority>/<collection>/<rkey>` ## Key Technologies | Component | Purpose | | -------------------------------------------- | ----------------------------------------------- | -| [DAG-CBOR](/garden/engineering/atproto/cbor) | Canonical binary serialization format | -| [MST](/garden/engineering/atproto/mst) | Content-addressed, verifiable key-value storage | -| [CAR](/garden/engineering/atproto/car) | Archive format for repository export/sync | +| [DAG-CBOR](/engineering/atproto/cbor) | Canonical binary serialization format | +| [MST](/engineering/atproto/mst) | Content-addressed, verifiable key-value storage | +| [CAR](/engineering/atproto/car) | Archive format for repository export/sync | | CIDs | Content identifiers linking to any data block | | XRPC | HTTP-based RPC protocol for API calls | ## Sync & Federation ### Repo Sync Repositories are synchronized using: -1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/garden/engineering/atproto/car). +1. **`com.atproto.sync.getRepo`**: Full repository export as a [CAR file](/engineering/atproto/car). 2. **`com.atproto.sync.subscribeRepos`**: Real-time firehose of commits across the network. ### Event Stream The firehose emits events: - **Commit**: New or updated records. - **Handle**: Handle changes. - **Identity**: DID document updates. - **Tombstone**: Account deletions. ## References - Official protocol specifications covering identity, data, and networking layers. [AT Protocol Specification](https://atproto.com/specs) - Home
Show diff
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 4e65215..0d2eae4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -25,16 +25,16 @@ Digital gardens have been fascinating for me for a long time. I miss the days of stumbling upon [information on an odd personal site](https://tilde.town/~dozens/sofa/) on the internet and want to be a part of bringing that back. I've tried keeping gardens in various iterations with tools like notion and even google drive, but nothing has been quite as consistent as a combination of some plaintext editor (VSCode & now Neovim) or "[Knowledge IDE](https://dev.to/envoy_/obsidian-an-ide-for-your-brain-1bn7)" like Obsidian. ## Inspiration Top of the list is definitely the [Blue Book](https://lyz-code.github.io/blue-book/). After starting a new python project and activating my virtual environment, I pretty much always install mkdocs with the material theme. That site, while also having some fantastic information, reminded me that I can just use mkdocs. -Also, take a look at my notes on [cultivating](/garden/writing/cultivation) a garden. +Also, take a look at my notes on [cultivating](/writing/cultivation) a garden. - Aristotle Problem
Show diff
diff --git a/src/content/docs/philosophy/aristotle-problem.md b/src/content/docs/philosophy/aristotle-problem.md index 1e4cdab..1b58c8b 100644 --- a/src/content/docs/philosophy/aristotle-problem.md +++ b/src/content/docs/philosophy/aristotle-problem.md @@ -5,16 +5,16 @@ title: Aristotle's Problem Domain Aristotle's problem domain was trying to define[^1] what makes a person good: 1. What **qualities** they ought to have? 2. How much should they have? 3. Is everyone capable of having them? 4. How do we get them? 5. What does having them look like? - The end goal is happiness (eudaimonia/flourishing) - To do so we need virtues (things that make us good at being human) - We're born with potential to get virtues - And a natural aptitude towards some - We become virtuous by doing virtuous things (habitual) [^1]: Schur, Michael. How to Be Perfect: A Foolproof Guide to Making the Correct Moral Decision in Every Situation You Ever Encounter Anywhere on Earth, Forever. -First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/garden/philosophy/book-schur-2023)) +First Simon&Schuster hardcover edition, Simon & Schuster, 2022. ([source](/philosophy/book-schur-2023)) - Bentham Scale
Show diff
diff --git a/src/content/docs/philosophy/bentham-scale.md b/src/content/docs/philosophy/bentham-scale.md index e08af64..896fe3a 100644 --- a/src/content/docs/philosophy/bentham-scale.md +++ b/src/content/docs/philosophy/bentham-scale.md @@ -1,17 +1,17 @@ --- title: Bentham's Scale --- - Intensity - Duration - Certainty - Propinquity (how soon it will happen) - Fecundity (how much pleasure) - Purity ($\frac{Pleasure}{Pain}$) - Extent (how many people benefit) - If you're acting publicly, spread as much pleasure you can ## Backlinks -1. [How to Be Perfect](/garden/philosophy/book-schur-2023) -2. [The Trolly Problem](/garden/philosophy/trolley-problem) +1. [How to Be Perfect](/philosophy/book-schur-2023) +2. [The Trolly Problem](/philosophy/trolley-problem) - Book Schur 2023
Show diff
diff --git a/src/content/docs/philosophy/book-schur-2023.mdx b/src/content/docs/philosophy/book-schur-2023.mdx index cda3c7b..7ac570f 100644 --- a/src/content/docs/philosophy/book-schur-2023.mdx +++ b/src/content/docs/philosophy/book-schur-2023.mdx @@ -12,57 +12,57 @@ Written by the venerable Michael Schur, creator of Parks & Recreation and of cou <Aside type="tip" title="Ethical Dilemma? Ask yourself..." icon='star'> 1. What are we doing? 2. Why are we doing it? 3. Is there something we could do that’s better? 4. Why is it better? </Aside> --- Everything has an ethical undercurrent and everything we do affects somebody Failure in trying to do the right thing is inevitable - But trying means we care Virtue ethics - what makes a person good or bad? - - [Aristotle](/garden/philosophy/aristotle-problem) wrestled with this + - [Aristotle](/philosophy/aristotle-problem) wrestled with this Brilliant instructors and wise friends are very important The Golden mean/goldilocks rule is that there is a spectrum that is like a see saw for virtues. If we veer to far towards one extreme, the see saw becomes imbalanced. - *ex.* Mildness is the golden mean of anger - Very challenging to define An excess of a virtue can harm the people around you If we don't take stock of our virtues, we can find ourselves moving towards extremes and these aspects can "calcify." As you practice, it becomes effortless - Schur talks about how Steve Carrell & Amy Poehler were like that with their comedy The closer we get to a golden mean, the easier it is to find others. - Examples include kindness and generosity Religious zealots ignore cruelty as it is not a slight against god Knowledge is how we escape cruelty --- <Aside type="note" title="The Trolley Problem" icon='information'> Do you let the trolley kill five workers ahead of you or do you switch to the other track and let one worker die? - Read more here: [link](/garden/philosophy/trolley-problem) + Read more here: [link](/philosophy/trolley-problem) --- by Philippa Foot </Aside> ## Quotes <Aside type="note" title="Hope" icon="open-book"> With enough work, no one is doomed to be forever deprived of magnanimity or courage or any other desirable quality, the way I’m doomed to get lost every time I walk around a parking garage looking for my car.[^1] </Aside> --- - Heuristic
Show diff
diff --git a/src/content/docs/philosophy/heuristic.md b/src/content/docs/philosophy/heuristic.md index 9990964..52e8d59 100644 --- a/src/content/docs/philosophy/heuristic.md +++ b/src/content/docs/philosophy/heuristic.md @@ -1,10 +1,10 @@ --- title: Heuristic --- # Heuristic - Enter an input and get an output (philosophical algorithm or function). - Gives us a rule of thumb for a certain scenario,[^1] as a guideline for our behavior -[^1]: [How to Be Perfect](/garden/philosophy/book-schur-2023) +[^1]: [How to Be Perfect](/philosophy/book-schur-2023) - Trolley Problem
Show diff
diff --git a/src/content/docs/philosophy/trolley-problem.md b/src/content/docs/philosophy/trolley-problem.md index 7021f29..e940eb5 100644 --- a/src/content/docs/philosophy/trolley-problem.md +++ b/src/content/docs/philosophy/trolley-problem.md @@ -1,24 +1,24 @@ --- title: The Trolley Problem --- - The problems arise when circumstances change - What if we're at a station with the lever and don't have the same amount of information? - What if we know someone on the tracks? - What if we push someone over a bridge to slow down the train and save everyone on the tracks? - Utilitarianism - Branch of consequentialism (only thing that matters is results) - The best action is what makes people the most happy (greatest happiness principle) - Developed by British philosophers Bentham (wanted himself studied and preserved after death) and Mill (had a rough childhood -- [Bentham's Scale](/garden/philosophy/bentham-scale) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) +- [Bentham's Scale](/philosophy/bentham-scale) is a way to quantify pleasure & pain (hedons & dolors - happiness points & sadness demerits) - Utilitarians believe all people's happiness matters equally - Correlation does not imply causation - Humans don't often know the consequences of their actions - Most human actions don't have all the information - before or after - Critiques of utilitarianism center on the wide differences between everybody's pleasure and pain - When our actions can cause pain and suffering as a result, utilitarianism fails to take into account our integrity - Advantage of utilitarianism is a straightforward distribution (those in need get the most) ## Source/Backlink -[How to Be Perfect](/garden/philosophy/book-schur-2023) +[How to Be Perfect](/philosophy/book-schur-2023) - Hindley Milner
Show diff
diff --git a/src/content/docs/programming/functional_programming/hindley_milner.md b/src/content/docs/programming/functional_programming/hindley_milner.md index d8454fe..f3c9100 100644 --- a/src/content/docs/programming/functional_programming/hindley_milner.md +++ b/src/content/docs/programming/functional_programming/hindley_milner.md @@ -176,27 +176,27 @@ with Γ mapping variables to schemes. The important rules (up to `let`) are: - infer `Γ ⊢ e₁ : τ₁`, `Γ ⊢ e₂ : τ₂`, - assert `τ₁` must be `τ₂ -> β` for fresh `β`, - unify `τ₁` with `τ₂ -> β`, giving substitution `S`, - result type is `S β`. 4. **Let**: For `let x = e₁ in e₂`: - infer `Γ ⊢ e₁ : τ₁`, - generalize `τ₁` to `σ = Gen(Γ, τ₁)`, - infer `Γ, x:σ ⊢ e₂ : τ₂`, - result type is `τ₂`. ## Algorithm W -See [Algorithm W](/garden/programming/functional_programming/algo-w) +See [Algorithm W](/programming/functional_programming/algo-w) ## Further Reading 1. Bernstein, Max. “Damas-Hindley-Milner Inference Two Ways.” Max Bernstein, 15 Oct. 2024, <https://bernsteinbear.com/blog/type-inference/>. 2. Diehl, Stephen. "Hindley-Milner Inference" Write You a Haskell. <https://smunix.github.io/dev.stephendiehl.com/fun/006_hindley_milner.html>. 3. Tuhola, Henri. Hindley-Milner Type System/Algorithm W Study. <https://boxbase.org//entries/2018/mar/5/hindley-milner>. 4. Hazelden, Phil. A Reckless Introduction to Hindley-Milner Type Inference. <https://reasonableapproximation.net/2019/05/05/hindley-milner.html>. [^1]: <https://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system> "Hindley–Milner type system" [^2]: <https://www.cs.tufts.edu/~nr/cs257/archive/martin-odersky/hmx.pdf> "Type Inference with Constrained Types" [^3]: <https://people.eecs.berkeley.edu/~necula/Papers/DamasMilnerAlgoW.pdf> "Principal type-schemes for functional programs" - Autonomy In Work
Show diff
diff --git a/src/content/docs/writing/autonomy_in_work.md b/src/content/docs/writing/autonomy_in_work.md index 31eae5a..ea96df5 100644 --- a/src/content/docs/writing/autonomy_in_work.md +++ b/src/content/docs/writing/autonomy_in_work.md @@ -1,9 +1,9 @@ --- title: Autonomy in Work --- This occurs when we are able to break down our work in to small chunks and steer it in a direction that is most interesting to us. This removes the need for us to use willpower to get things done.[^ref] -[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017) - P. 138 +[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017) - P. 138 - Book Ahrens 2017
Show diff
diff --git a/src/content/docs/writing/book-ahrens-2017.mdx b/src/content/docs/writing/book-ahrens-2017.mdx index 4e39ff5..19e6041 100644 --- a/src/content/docs/writing/book-ahrens-2017.mdx +++ b/src/content/docs/writing/book-ahrens-2017.mdx @@ -1,103 +1,103 @@ --- title: How to Take Smart Notes --- import { Aside } from '@astrojs/starlight/components'; Two-Slip boxes in one markdown file: note and reference - notes extend and relate to other notes, not in isolation (one note can exist in different contexts - basically, we can understand how different ideas[^1]) -Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/garden/writing/write_to_learn) +Read, Think, Understand - then write your note (woops) - we have to [write to externalize our ideas](/writing/write_to_learn) Life requires context switching, and notes with an index can help me pick up where I left off in the thought process. This is important for my work, as I am a knowledge worker Strip the workflow of everything that can be considered unimportant (I should probably stop using Notion for note taking - only as content management) The author advises that we always have the tools at hand - pen & paper (anything to capture with) A journal is a "graveyard for thoughts", the slip box should be for notes[^2] Asking yourself what you should learn is a useless question - it's easier to do things with a clear view of the destination - Deliberate practice helps us become better at making this journey[^3] > Nothing counts other than writing. The main goal[^4] of notes is to convey the truth (publishable insight) Note types: Fleeting, Permanent, Project (-specific) In order to find a topic, you need to have studied a subject - This makes me think of an old interview of Alexisonfire, where George says to make music, you have to listen to music. > By focusing on what is interesting and keeping written track of *your own intellectual development*, > topics, questions and arguments will emerge from the material without force. Rewarding work starts the positive feedback loop - Writing provides the feedback portion (we're forced to assess if we're understanding the material) -[Mere Exposure Effect](/garden/writing/mere_exposure_effect): If we do something a lot, we *think* we're good at it, even if we're not +[Mere Exposure Effect](/writing/mere_exposure_effect): If we do something a lot, we *think* we're good at it, even if we're not Focused attention is not very long. New technology damages our ability to practice sustained attention (where we work on one thing at a time) Creativity requires keeping an open mind and being able to switch to a narrow, analytical approach Memo-ize memories - group in to bundles, rather than discrete facts "Mind Like Water" - get knowledge out of our short term memory Willpower is like muscles - requires rest and gets exhausted quickly but can be strengthened Hand writing facilitates understanding because it is slow - college students have to understand what they hear rather than copy it down Shorter, in your own words allows us to focus on patterns, frames, and categories of an excerpt Re-reading breeds familiarity, writing forces us to confront misunderstanding - Cramming is for short term retention, not for learning The brain prioritizes comfort and its own happiness (like ego in The Power of Now) - Writing was Richard Feynman's thinking process (think outside your brain) -Forgetting can sometimes be [done by our minds](/garden/writing/active_inhibition) as a filter so we don't get flooded with memories and associations (think join models in SQL) +Forgetting can sometimes be [done by our minds](/writing/active_inhibition) as a filter so we don't get flooded with memories and associations (think join models in SQL) Memory can be measured by storage and retrieval strength - Storage strength can't be improved Linking is key! - Keep an eye towards other notes and contexts such that you can build the matrix around things you're interested in -Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/garden/writing/feature_positive_effect)) +Contradictions, paradoxes and problems help us reassess pre-existing knowledge stored in the slip-box (corrects for the [Feature Positive Effect](/writing/feature_positive_effect)) Remember that the slip-box is just a tool[^5] -[Worldly Wisdom](/garden/writing/worldly_wisdom): hanging life experiences on mental models +[Worldly Wisdom](/writing/worldly_wisdom): hanging life experiences on mental models Spaced repitition and active recall are important for information retention. One idea per permanent note - place limits so that they stay concise. - Structure (experiment) and restrictions (assess what is important) are necessary for creativity The brain prioritizes information that is recently acquired and with emotions attached to it Evolution works by trial & error, not planning[^6] -- [Motivation](/garden/writing/motivation_when_studying) is relational (students must identify with and see the purpose of their work) - - And be [free](/garden/writing/autonomy_in_work) +- [Motivation](/writing/motivation_when_studying) is relational (students must identify with and see the purpose of their work) + - And be [free](/writing/autonomy_in_work) Athletes are more motivated when they imagine the training it takes to win.[^7] Build new habits to replace old ones, don't force old habits away - - The [goal of learning](/garden/writing/goal_of_learning) is to evolve + - The [goal of learning](/writing/goal_of_learning) is to evolve ## My Routine/Takeaways Keep a pen & paper handy at all times (if anything, just to avoid opening your phone when in the middle of a book) Abandon the notion of making perfect notes. Do you think the multicolored shit people made in college is something that would have helped you? Why not just make art instead? When processing notes, open up the source with anything you've highlighted - *ex. the Kindle notes & highlights for this book* Many of my attitudes towards learning are not conducive to learning, but to accomplishing a very specific task. Turn the writing everything and thinking about process in to a hobby [^1]: Page 20 - Goal Of Learning
Show diff
diff --git a/src/content/docs/writing/goal_of_learning.md b/src/content/docs/writing/goal_of_learning.md index c26e9fa..3bb72e6 100644 --- a/src/content/docs/writing/goal_of_learning.md +++ b/src/content/docs/writing/goal_of_learning.md @@ -1,9 +1,9 @@ --- title: Goal of Learning --- > The goal of learning is not to accumulate knowledge but about becoming a different person with a different way of thinking. The author is trying to say[^1] that we learn to grow, not collect. -[^1]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017) +[^1]: [How to Take Smart Notes](/writing/book-ahrens-2017) - On Writing
Show diff
diff --git a/src/content/docs/writing/on_writing.md b/src/content/docs/writing/on_writing.md index 1cfdf25..86d07c0 100644 --- a/src/content/docs/writing/on_writing.md +++ b/src/content/docs/writing/on_writing.md @@ -1,14 +1,14 @@ --- title: On Writing sidebar: order: 1 badge: text: Start variant: note --- This section has notes about topics related to writing stories and educational material. It includes information about creating a site like this, and the backbone of my notes, writing to learn and using a zettlekasten system. -Here's a seed: [On Cultivating a Digital Garden](/garden/writing/cultivation) +Here's a seed: [On Cultivating a Digital Garden](/writing/cultivation) - Write To Learn
Show diff
diff --git a/src/content/docs/writing/write_to_learn.md b/src/content/docs/writing/write_to_learn.md index 873dfbe..553b59e 100644 --- a/src/content/docs/writing/write_to_learn.md +++ b/src/content/docs/writing/write_to_learn.md @@ -1,14 +1,14 @@ --- title: Write to Learn --- When you write as you learn, you create a tangible outcome out of what you've read.[^ref] I think what inhibits me is that I want everything to be perfect and pristine, when in reality it's the substance that matters. Notes can be messy and disorganized, so long as you understand what you're putting in your brain. - Write down *anything* you think is helpful to understanding or need to remember - When you process, then you can create perfection (the structure is important) -[^ref]: [How to Take Smart Notes](/garden/writing/book-ahrens-2017) +[^ref]: [How to Take Smart Notes](/writing/book-ahrens-2017)