constella 0.1.0

package/skills/languages/erlang/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: erlang
+description: Erlang is a functional, concurrent language built on the BEAM VM and OTP framework for fault-tolerant, distributed, soft-real-time systems using lightweight processes and message passing; consult when writing Erlang, using OTP behaviours (gen_server/supervisor), pattern matching, or building telecom-grade, highly available systems.
+domain: language
+category: language
+tags: [erlang, beam, otp, concurrency, actor-model, distributed, fault-tolerant]
+official_sources:
+  - https://www.erlang.org/docs
+  - https://github.com/erlang/otp
+  - https://www.erlang.org/downloads
+verified: 2026-06-17
+---
+
+# Erlang
+
+## Overview
+Erlang is a functional, concurrent language that runs on the BEAM virtual machine and ships with OTP, a framework for building fault-tolerant, distributed, soft-real-time systems. Concurrency is modeled with cheap isolated processes communicating by asynchronous message passing ("let it crash" with supervision). Read this when writing Erlang, using OTP behaviours like `gen_server` and `supervisor`, or building highly available distributed systems.
+
+## Official sources
+- Docs: https://www.erlang.org/docs
+- Repo: https://github.com/erlang/otp
+- Install: https://www.erlang.org/downloads
+
+## Install / setup
+```bash
+# macOS (Homebrew); or use the installers/source at erlang.org/downloads
+brew install erlang
+erl  # start the Erlang shell
+```
+Install options per https://www.erlang.org/downloads (source build, prebuilt packages, kerl/asdf/mise are all documented there).
+
+## Core concepts
+- **Lightweight processes** — `spawn` creates isolated, scheduler-managed processes (not OS threads); millions can run.
+- **Message passing** — processes communicate with `!` (send) and `receive`; no shared mutable state.
+- **Pattern matching** — bind and destructure in function heads, `case`, and `receive` clauses.
+- **Immutability & single assignment** — variables are bound once; data is immutable.
+- **OTP behaviours** — `gen_server`, `supervisor`, `application`, and `gen_statem` encode proven design patterns.
+- **Supervision trees & "let it crash"** — supervisors restart failed children rather than coding defensive error handling.
+- **Hot code loading** — modules can be upgraded in a running system without downtime.
+- **Distribution** — nodes connect transparently; remote sends look like local sends.
+
+## Best practices
+- Structure systems as supervision trees using OTP behaviours instead of raw `spawn` (https://www.erlang.org/doc/system/design_principles.html).
+- Embrace "let it crash": handle the expected path, let supervisors recover from the unexpected (https://www.erlang.org/doc/system/sup_princ.html).
+- Keep processes small and single-purpose; isolate state per process (https://www.erlang.org/docs).
+- Use `gen_server` for stateful services rather than hand-rolling receive loops (https://www.erlang.org/doc/system/gen_server_concepts.html).
+
+## Common pitfalls
+- Unbounded mailbox growth from selective `receive` not matching messages → match all expected messages and drain/log unexpected ones.
+- Treating processes as cheap shared-memory objects → they have isolated heaps; pass data via messages, copying cost matters for large terms.
+- Blocking a `gen_server` callback with long work → offload to a worker/task process to keep the server responsive.
+
+## Examples
+```erlang
+-module(counter).
+-behaviour(gen_server).
+-export([start_link/0, inc/0, get/0]).
+-export([init/1, handle_call/3, handle_cast/2]).
+
+start_link() -> gen_server:start_link({local, ?MODULE}, ?MODULE, 0, []).
+inc()        -> gen_server:cast(?MODULE, inc).
+get()        -> gen_server:call(?MODULE, get).
+
+init(N)                  -> {ok, N}.
+handle_cast(inc, N)      -> {noreply, N + 1}.
+handle_call(get, _F, N)  -> {reply, N, N}.
+```
+
+## Further reading
+- https://www.erlang.org/docs — official Erlang/OTP documentation hub
+- https://www.erlang.org/doc/system/design_principles.html — OTP design principles
+- https://www.erlang.org/course — getting-started course on erlang.org
+
+## Related skills
+- ../clojure — shares a functional, immutability-first philosophy on a VM
+- ../haskell — another functional language; contrast pure/lazy vs concurrent/eager

package/skills/languages/go/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: go
+description: Compiled, concurrent language for simple, reliable network services; consult for goroutines, modules, and tooling.
+domain: language
+category: language
+tags: [go, golang, concurrency, goroutines, modules]
+official_sources:
+  - https://go.dev/doc/
+  - https://github.com/golang/go
+  - https://go.dev/dl/
+verified: 2026-06-16
+---
+
+# Go
+
+## Overview
+Go is an open-source programming language that makes it easy to build simple, reliable, and efficient software. It is statically typed and compiled, ships with a garbage collector, and provides built-in concurrency primitives (goroutines and channels) designed for network services and tooling. Read this for the module system, concurrency model, and the standard toolchain.
+
+## Official sources
+- Docs: https://go.dev/doc/
+- Repo: https://github.com/golang/go
+- Install / download: https://go.dev/dl/
+
+## Install / setup
+Download the installer for your platform from https://go.dev/dl/ and follow the instructions at https://go.dev/doc/install. Verify the install:
+```bash
+go version
+```
+
+## Core concepts
+- Goroutines and channels: lightweight concurrent functions started with `go`, communicating over typed channels ("share memory by communicating").
+- Modules: dependency management via `go.mod`/`go.sum`; a module is a versioned collection of packages.
+- Interfaces are implicit: a type satisfies an interface simply by implementing its methods — no explicit `implements`.
+- Explicit error handling: functions return `error` values that callers check; no exceptions for ordinary control flow.
+- Structs and methods: data is grouped in structs; methods attach to types via receivers; no class inheritance, composition instead.
+- The standard toolchain: `go build`, `go run`, `go test`, `go fmt`, and `go vet` are part of the official distribution.
+- Defer/panic/recover: `defer` schedules cleanup; `panic`/`recover` are for truly exceptional conditions, not normal errors.
+
+## Best practices
+- Format code with `gofmt`/`go fmt` — canonical formatting is part of the language culture and is non-negotiable in idiomatic Go.
+- Handle every returned `error`; wrap with context using `fmt.Errorf("...: %w", err)` rather than discarding it.
+- Use `context.Context` to carry cancellation and deadlines through call chains, especially for servers.
+- Keep interfaces small and define them at the consumer; prefer composition over inheritance.
+
+## Common pitfalls
+- Ignoring returned errors (`val, _ := ...`) → silently drops failures; check and propagate them.
+- Loop-variable capture in goroutines/closures → in older Go versions the variable was shared; capture explicitly or rely on the per-iteration scoping of recent Go.
+- Unbuffered channel deadlocks → a send blocks until a receiver is ready; ensure a consumer exists or use buffering/`select`.
+- Data races on shared state → guard with channels, `sync.Mutex`, or run `go test -race` to detect them.
+
+## Examples
+```go
+package main
+
+import (
+	"fmt"
+	"sync"
+)
+
+func main() {
+	var wg sync.WaitGroup
+	results := make(chan int, 3)
+	for i := 1; i <= 3; i++ {
+		wg.Add(1)
+		go func(n int) {
+			defer wg.Done()
+			results <- n * n
+		}(i)
+	}
+	wg.Wait()
+	close(results)
+	for r := range results {
+		fmt.Println(r)
+	}
+}
+```
+
+## Further reading
+- A Tour of Go: https://go.dev/tour/
+- Effective Go: https://go.dev/doc/effective_go
+
+## Related skills
+- (sibling language skills under ../)

package/skills/languages/haskell/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: haskell
+description: Haskell is a statically typed, purely functional, lazily evaluated language with type inference and monadic effects, compiled by GHC; consult when writing Haskell, installing the toolchain via GHCup, using Cabal or Stack, reasoning about type classes, monads, laziness, or pure functional design.
+domain: language
+category: language
+tags: [haskell, functional, ghc, cabal, stack, type-classes, monads]
+official_sources:
+  - https://www.haskell.org/documentation/
+  - https://gitlab.haskell.org/ghc/ghc
+  - https://www.haskell.org/ghcup/install/
+verified: 2026-06-17
+---
+
+# Haskell
+
+## Overview
+Haskell is a statically typed, purely functional language with global type inference, lazy (non-strict) evaluation, and effects tracked in the type system via monads. The reference compiler is GHC, and packages come from Hackage/Stackage. Read this when writing Haskell, setting up the toolchain with GHCup, building with Cabal or Stack, or reasoning about type classes, monads, and laziness.
+
+## Official sources
+- Docs: https://www.haskell.org/documentation/
+- Repo: https://gitlab.haskell.org/ghc/ghc
+- Install: https://www.haskell.org/ghcup/install/
+
+## Install / setup
+```bash
+# GHCup installs GHC, Cabal, Stack, and HLS (Linux/macOS/WSL)
+curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
+```
+Command per https://www.haskell.org/ghcup/install/ (Windows uses the PowerShell bootstrap on the same page).
+
+## Core concepts
+- **Purity & referential transparency** — functions have no side effects; the same input always yields the same output.
+- **Lazy evaluation** — expressions evaluate only when needed, enabling infinite data structures but requiring care with space.
+- **Strong static types + inference** — the compiler infers most types; `Maybe`/`Either` encode absence and errors without exceptions.
+- **Type classes** — ad-hoc polymorphism (`Eq`, `Ord`, `Functor`, `Monad`) constrain types by capability.
+- **Monads & `do` notation** — sequence effectful computations (`IO`, `Maybe`, `State`) while staying pure.
+- **Algebraic data types & pattern matching** — `data` declares sum/product types deconstructed by pattern match.
+- **GHC & extensions** — the de-facto compiler; `{-# LANGUAGE ... #-}` pragmas enable language extensions.
+- **Cabal / Stack** — build tools; Cabal uses `.cabal`/`cabal.project`, Stack pins curated Stackage snapshots.
+
+## Best practices
+- Manage the toolchain with GHCup and an editor using HLS for type-aware feedback (https://www.haskell.org/ghcup/steps/).
+- Compile with `-Wall` and fix warnings; let types guide design (https://downloads.haskell.org/ghc/latest/docs/users_guide/using-warnings.html).
+- Prefer total functions; use `Maybe`/`Either` over partial functions like `head` on possibly-empty lists (https://www.haskell.org/documentation/).
+- Pin reproducible builds with a Stackage resolver or a Cabal freeze file (https://docs.haskellstack.org/).
+
+## Common pitfalls
+- Thunk buildup from lazy accumulators → use strict folds (`foldl'`) and `BangPatterns`/`seq` to force evaluation.
+- Using partial functions (`head`, `fromJust`) on empty/`Nothing` values → pattern-match or use safe variants.
+- Confusing `IO a` ordering → sequence effects with `do`/`>>=`; pure values never "run".
+
+## Examples
+```haskell
+import Data.List (sortOn, group, sort)
+import Data.Ord (Down(..))
+
+wordFreq :: String -> [(String, Int)]
+wordFreq = sortOn (Down . snd)
+         . map (\ws -> (head ws, length ws))
+         . group . sort . words
+```
+
+## Further reading
+- https://www.haskell.org/documentation/ — official documentation hub
+- https://downloads.haskell.org/ghc/latest/docs/users_guide/ — GHC user's guide
+- https://hackage.haskell.org/ — central package repository
+
+## Related skills
+- ../clojure — another functional language built on immutability and pure functions
+- ../erlang — functional language with a different (eager, concurrency-first) emphasis

package/skills/languages/java/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: java
+description: JVM object-oriented, statically typed language; consult for OOP, the JDK toolchain, and runtime/build basics.
+domain: language
+category: language
+tags: [java, jvm, openjdk, oop, temurin]
+official_sources:
+  - https://docs.oracle.com/en/java/
+  - https://github.com/openjdk/jdk
+  - https://adoptium.net/installation/
+verified: 2026-06-16
+---
+
+# Java
+
+## Overview
+Java is a statically typed, object-oriented, class-based language that compiles to bytecode and runs on the Java Virtual Machine (JVM), giving it "write once, run anywhere" portability. OpenJDK is the open-source reference implementation; Eclipse Temurin (from Adoptium) is a widely used prebuilt OpenJDK distribution. Read this for OOP fundamentals, the JDK toolchain, and runtime/build basics.
+
+## Official sources
+- Docs: https://docs.oracle.com/en/java/
+- Repo (OpenJDK): https://github.com/openjdk/jdk
+- Install (Eclipse Temurin / Adoptium): https://adoptium.net/installation/
+
+## Install / setup
+Install Eclipse Temurin (OpenJDK). On Windows via winget, per https://adoptium.net/installation/:
+```bash
+winget install EclipseAdoptium.Temurin.25.JDK
+```
+On other platforms use the package managers, installers, or archives listed on the Adoptium installation page.
+
+## Core concepts
+- Classes and objects: code is organized into classes; objects are instances. Single inheritance of classes, multiple inheritance of interfaces.
+- Static typing and the type system: types are checked at compile time; generics provide type-safe collections and APIs.
+- The JVM and bytecode: `javac` compiles `.java` to `.class` bytecode that the JVM executes, with JIT compilation and garbage collection.
+- Interfaces and abstraction: interfaces define contracts; abstract classes provide partial implementation.
+- Checked vs. unchecked exceptions: checked exceptions must be declared or handled; unchecked (RuntimeException) need not be.
+- Packages and the module system: packages namespace classes; the JPMS module system (`module-info.java`) adds explicit dependencies.
+- Build tools and the classpath: Maven/Gradle manage dependencies and builds; the classpath/modulepath locates classes at runtime.
+
+## Best practices
+- Program to interfaces, not implementations, so code depends on contracts rather than concrete classes.
+- Prefer immutability for value types and use `final` where appropriate to make intent and thread-safety clearer.
+- Use a build tool (Maven or Gradle) and declared dependencies instead of manually managing JARs on the classpath.
+- Close resources deterministically with try-with-resources for anything implementing `AutoCloseable`.
+
+## Common pitfalls
+- Calling methods on a `null` reference → guard with checks or use `Optional` to express absence at API boundaries.
+- Comparing objects with `==` instead of `.equals()` → `==` compares references; override/use `equals`/`hashCode` consistently.
+- Forgetting to close streams/connections → leaks resources; use try-with-resources.
+- Mutable shared state across threads without synchronization → causes races; use immutability, `synchronized`, or `java.util.concurrent`.
+
+## Examples
+```java
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+public class ReadLines {
+    public static void main(String[] args) throws Exception {
+        List<String> lines = Files.readAllLines(Path.of("data.txt"));
+        lines.forEach(System.out::println);
+    }
+}
+```
+
+## Further reading
+- Java SE documentation (Oracle): https://docs.oracle.com/en/java/javase/
+- OpenJDK project: https://openjdk.org/
+
+## Related skills
+- ../kotlin — modern JVM language interoperable with Java

package/skills/languages/javascript/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: javascript
+description: Dynamic, prototype-based language of the web (ECMAScript); consult for core semantics, async, and modern syntax.
+domain: language
+category: language
+tags: [javascript, ecmascript, web, async, es modules]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/JavaScript
+  - https://github.com/tc39/ecma262
+verified: 2026-06-16
+---
+
+# JavaScript
+
+## Overview
+JavaScript is a lightweight, interpreted (or just-in-time compiled) programming language with first-class functions. Best known as the scripting language of web pages, it also runs in many non-browser environments such as Node.js. It is a prototype-based, garbage-collected, dynamic, multi-paradigm language standardized as ECMAScript. Read this for core language semantics, asynchronous patterns, and modern module syntax.
+
+## Official sources
+- Docs (reference): https://developer.mozilla.org/en-US/docs/Web/JavaScript
+- Language standard repo (ECMA-262 / TC39): https://github.com/tc39/ecma262
+
+## Core concepts
+- Dynamic typing: variables are not bound to a type; values carry types and can change. Primitives include string, number, bigint, boolean, undefined, null, symbol; everything else is an object.
+- First-class functions and closures: functions are values that can be passed, returned, and capture their lexical scope.
+- Prototype-based inheritance: objects inherit directly from other objects via the prototype chain; `class` syntax is sugar over prototypes.
+- The event loop and asynchronous model: single-threaded with non-blocking I/O via callbacks, Promises, and `async`/`await`.
+- Scoping and hoisting: `let`/`const` are block-scoped (with a temporal dead zone); `var` is function-scoped; declarations are hoisted.
+- Strict equality vs. coercion: `===` compares without type coercion; `==` performs coercion and is a frequent source of surprises.
+- ES modules: `import`/`export` provide the standardized module system across browsers and Node.js.
+
+## Best practices
+- Prefer `const` by default and `let` when reassignment is needed; avoid `var` to escape function-scope and hoisting surprises (per MDN guidance).
+- Use strict equality (`===` / `!==`) rather than loose equality to avoid implicit coercion bugs.
+- Handle Promise rejections — `await` inside `try/catch`, or attach `.catch()` — to avoid unhandled rejections.
+- Use ES module `import`/`export` for clear, statically analyzable dependencies.
+
+## Common pitfalls
+- Relying on `this` binding inside detached callbacks → use arrow functions (which capture lexical `this`) or bind explicitly.
+- Loose equality and truthiness surprises (`0`, `""`, `null`, `undefined`, `NaN`) → use `===` and explicit checks.
+- Floating-point arithmetic precision (e.g. `0.1 + 0.2 !== 0.3`) → round for display or use integer/bigint math where exactness matters.
+- Mutating shared objects/arrays unexpectedly → copy (spread, structuredClone) before mutating when isolation is needed.
+
+## Examples
+```javascript
+async function fetchUser(id) {
+  try {
+    const res = await fetch(`/api/users/${id}`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } catch (err) {
+    console.error("fetchUser failed", err);
+    throw err;
+  }
+}
+```
+
+## Further reading
+- MDN JavaScript Guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide
+- ECMAScript draft spec: https://tc39.es/ecma262/
+
+## Related skills
+- ../typescript — typed superset that compiles to JavaScript

package/skills/languages/kotlin/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: kotlin
+description: Concise, modern JVM language fully interoperable with Java; consult for null safety, coroutines, and tooling.
+domain: language
+category: language
+tags: [kotlin, jvm, null-safety, coroutines, multiplatform]
+official_sources:
+  - https://kotlinlang.org/docs/home.html
+  - https://github.com/JetBrains/kotlin
+  - https://kotlinlang.org/docs/getting-started.html
+verified: 2026-06-16
+---
+
+# Kotlin
+
+## Overview
+Kotlin is a concise, statically typed, multiplatform language developed by JetBrains. It runs primarily on the JVM with full two-way interoperability with Java, and also targets Android, native, and other platforms. It emphasizes null safety, expressive syntax, and structured concurrency via coroutines. Read this for null safety, coroutines, and the recommended getting-started path.
+
+## Official sources
+- Docs: https://kotlinlang.org/docs/home.html
+- Repo: https://github.com/JetBrains/kotlin
+- Getting started: https://kotlinlang.org/docs/getting-started.html
+
+## Install / setup
+Kotlin ships with every IntelliJ IDEA and Android Studio release, so installing one of those IDEs is the recommended way to start (per the getting-started page). To install the standalone command-line compiler via SDKMAN! (per https://kotlinlang.org/docs/command-line.html):
+```bash
+sdk install kotlin
+```
+
+## Core concepts
+- Null safety: types are non-nullable by default; nullable types are marked with `?`, and the compiler forces you to handle `null`.
+- Concise syntax: type inference, data classes, properties, and expression bodies reduce boilerplate versus Java.
+- Java interoperability: Kotlin calls Java and Java calls Kotlin seamlessly, easing incremental adoption in existing JVM codebases.
+- Coroutines: lightweight, structured concurrency with `suspend` functions for non-blocking asynchronous code.
+- Extension functions: add functions to existing types without inheritance or modifying the original class.
+- Immutability by default intent: `val` (read-only) vs. `var` (mutable); prefer `val`.
+- Smart casts and `when`: after a type/null check the compiler auto-casts; `when` is a powerful expression-based branch.
+
+## Best practices
+- Prefer `val` over `var` and immutable collections to make state explicit and reduce bugs.
+- Use the null-safety operators (`?.`, `?:`, `!!` sparingly) instead of defensive null checks; avoid `!!` except where null is truly impossible.
+- Use coroutines with structured concurrency (scopes) for async work rather than raw threads or callbacks.
+- Model data with `data class` and represent restricted hierarchies with `sealed` classes for exhaustive `when`.
+
+## Common pitfalls
+- Overusing the `!!` not-null assertion → it throws NPE at runtime, defeating null safety; prefer `?.`/`?:` or restructure.
+- Platform types from Java (`String!`) → Java values have unknown nullability; annotate or guard them at the boundary.
+- Launching coroutines without a proper scope → can leak work; use lifecycle/structured scopes so they are cancelled correctly.
+- Assuming `==` is identity → in Kotlin `==` calls `equals` (structural); use `===` for referential equality.
+
+## Examples
+```kotlin
+fun greet(name: String?): String {
+    return "Hello, ${name ?: "guest"}"
+}
+
+fun main() {
+    println(greet("Ada"))
+    println(greet(null))
+}
+```
+
+## Further reading
+- Kotlin Tour: https://kotlinlang.org/docs/kotlin-tour-welcome.html
+- Coroutines guide: https://kotlinlang.org/docs/coroutines-guide.html
+
+## Related skills
+- ../java — the JVM language Kotlin interoperates with

package/skills/languages/lua/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: lua
+description: Lua is a small, fast, dynamically typed scripting language designed to be embedded in host applications via a clean C API, with tables as its sole data-structuring mechanism; consult when writing Lua, embedding/extending it from C, using metatables, coroutines, or scripting games, Neovim, Redis, or nginx.
+domain: language
+category: language
+tags: [lua, scripting, embedded, dynamic, tables, coroutines, c-api]
+official_sources:
+  - https://www.lua.org/manual/5.5/
+  - https://www.lua.org/
+  - https://www.lua.org/download.html
+verified: 2026-06-17
+---
+
+# Lua
+
+## Overview
+Lua is a lightweight, dynamically typed scripting language built around a single data structure (the table) and designed to be embedded into host programs through a small, well-documented C API. It is fast, portable (pure ISO C), and widely used for game scripting, Neovim config, Redis, and nginx (OpenResty). Read this when writing Lua, embedding or extending it from C, or using metatables and coroutines.
+
+## Official sources
+- Docs: https://www.lua.org/manual/5.5/
+- Home: https://www.lua.org/ — the authoritative source for Lua is lua.org, not GitHub
+- Install: https://www.lua.org/download.html
+- Mirror (unofficial): https://github.com/lua/lua — read-only mirror of Lua dev code, "mirrored irregularly"; no PRs accepted (see its README). Official releases come from lua.org.
+
+## Install / setup
+```bash
+curl -L -R -O https://www.lua.org/ftp/lua-5.5.0.tar.gz
+tar zxf lua-5.5.0.tar.gz
+cd lua-5.5.0
+make all test
+```
+Build steps per https://www.lua.org/download.html (Lua compiles unmodified on any platform with an ISO C compiler).
+
+## Core concepts
+- **Tables** — the only structured type; serve as arrays, dictionaries, objects, and namespaces.
+- **Metatables & metamethods** — `__index`, `__newindex`, `__add`, etc., customize behavior and implement OOP/inheritance.
+- **First-class functions & closures** — functions are values with lexical scoping over `upvalues`.
+- **Coroutines** — cooperative multitasking via `coroutine.create`/`resume`/`yield`; not OS threads.
+- **The C API & stack** — host programs push/pop Lua values on a virtual stack to call into and out of Lua.
+- **1-based indexing** — arrays and string positions start at 1, not 0.
+- **`nil` and truthiness** — only `nil` and `false` are falsy; `0` and `""` are truthy.
+- **Lua vs LuaJIT** — reference Lua (lua.org) vs the separate high-performance JIT implementation.
+
+## Best practices
+- Localize frequently used globals (`local sqrt = math.sqrt`) for speed and clarity (https://www.lua.org/manual/5.5/).
+- Use `pcall`/`xpcall` to handle runtime errors instead of letting them propagate (https://www.lua.org/manual/5.5/manual.html#pdf-pcall).
+- Implement OOP with metatables and `__index` rather than copying methods per instance (https://www.lua.org/pil/16.html).
+- When embedding, always balance the C API stack and check `lua_pcall` return codes (https://www.lua.org/manual/5.5/manual.html#4).
+
+## Common pitfalls
+- Assuming 0-based indexing → Lua arrays/strings are 1-based; iterate with `ipairs` for sequences.
+- Treating `0` or `""` as false → only `nil`/`false` are falsy; test explicitly with `== nil`.
+- Holes in a "sequence" table breaking `#t` and `ipairs` → keep array tables contiguous or track length yourself.
+
+## Examples
+```lua
+-- Metatable-based class
+local Account = {}
+Account.__index = Account
+
+function Account.new(balance)
+  return setmetatable({ balance = balance or 0 }, Account)
+end
+
+function Account:deposit(n) self.balance = self.balance + n end
+
+local a = Account.new(100)
+a:deposit(50)
+print(a.balance)  --> 150
+```
+
+## Further reading
+- https://www.lua.org/manual/5.5/ — Lua 5.5 reference manual (language, libraries, C API)
+- https://www.lua.org/pil/ — Programming in Lua (first edition, online)
+- https://www.lua.org/docs.html — documentation index
+
+## Related skills
+- ../c — Lua is written in ISO C and embeds through its C API
+- ../clojure — fellow dynamically typed, functional-leaning language

package/skills/languages/objectivec/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: objectivec
+description: Objective-C is a superset of C that adds Smalltalk-style message passing and a dynamic runtime, historically the primary language for Apple macOS and iOS development with Cocoa/Cocoa Touch; consult when writing or maintaining Objective-C, using ARC, the runtime, categories, protocols, or bridging with Swift and C.
+domain: language
+category: language
+tags: [objectivec, apple, cocoa, ios, macos, runtime, arc]
+official_sources:
+  - https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/
+  - https://developer.apple.com/documentation/objectivec
+  - https://developer.apple.com/xcode/
+verified: 2026-06-17
+---
+
+# Objective-C
+
+## Overview
+Objective-C is a strict superset of C that adds object-oriented programming through Smalltalk-style message passing and a dynamic runtime. It was the primary language for Apple's Cocoa (macOS) and Cocoa Touch (iOS) frameworks before Swift and remains common in legacy apps and frameworks. Read this when writing or maintaining Objective-C, using ARC memory management, the runtime, categories/protocols, or bridging with Swift and C.
+
+## Official sources
+- Docs: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/
+- Repo: https://developer.apple.com/documentation/objectivec (runtime reference; the compiler is Apple Clang, https://github.com/llvm/llvm-project)
+- Install: https://developer.apple.com/xcode/
+
+## Install / setup
+```bash
+# Install Xcode's command-line tools (includes Apple Clang), then compile:
+xcode-select --install
+clang -fobjc-arc -framework Foundation hello.m -o hello
+```
+Xcode/tooling per https://developer.apple.com/xcode/ ; ARC and Foundation flags per https://developer.apple.com/documentation/objectivec.
+
+## Core concepts
+- **Message passing** — `[receiver message:arg]` sends messages; dispatch is resolved dynamically at runtime.
+- **Classes & instances** — `@interface`/`@implementation` define classes; `id` is the dynamic object type.
+- **ARC** — Automatic Reference Counting inserts retain/release; manage cycles with `weak`/`strong` references.
+- **Protocols** — declare method contracts (`@protocol`) adopted by classes; similar to interfaces.
+- **Categories & extensions** — add methods to existing classes (`@interface NSString (MyExtras)`) without subclassing.
+- **Properties** — `@property` synthesizes accessors with attributes (`nonatomic`, `strong`, `copy`, `weak`).
+- **The Objective-C runtime** — introspection, dynamic method resolution, and swizzling via `<objc/runtime.h>`.
+- **Foundation/Cocoa** — `NSString`, `NSArray`, `NSDictionary`, and the broader framework stack.
+
+## Best practices
+- Use ARC (`-fobjc-arc`) and reason about ownership with `strong`/`weak`/`copy` property attributes (https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/).
+- Adopt `NS_ASSUME_NONNULL_BEGIN`/nullability annotations to improve Swift interop (https://developer.apple.com/documentation/objectivec).
+- Prefer protocols and composition over deep class hierarchies (https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/WorkingwithProtocols/WorkingwithProtocols.html).
+- Use `copy` for mutable-backed properties like `NSString`/`NSArray` to avoid external mutation.
+
+## Common pitfalls
+- Retain cycles between objects (e.g., delegate/block captures `self`) → declare back-references `weak` and use `__weak`/`__strong` in blocks.
+- Sending messages to `nil` returns zero/`nil` silently → check assumptions rather than relying on no-op dispatch.
+- Mutating a collection while enumerating it → enumerate a copy or collect changes and apply afterward.
+
+## Examples
+```objc
+#import <Foundation/Foundation.h>
+
+@interface Greeter : NSObject
+- (NSString *)greet:(NSString *)name;
+@end
+
+@implementation Greeter
+- (NSString *)greet:(NSString *)name {
+    return [NSString stringWithFormat:@"Hello, %@!", name];
+}
+@end
+
+int main(void) {
+    @autoreleasepool {
+        Greeter *g = [Greeter new];
+        NSLog(@"%@", [g greet:@"World"]);
+    }
+    return 0;
+}
+```
+
+## Further reading
+- https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/ — Programming with Objective-C guide
+- https://developer.apple.com/documentation/objectivec — Objective-C runtime reference
+- https://developer.apple.com/documentation/swift/objective-c-and-c-code-customization — Swift/Objective-C interop
+
+## Related skills
+- ../c — Objective-C is a strict superset of C and compiles C directly
+- ../lua — another language frequently embedded in iOS/macOS apps