feat: PR-1 add project infrastructure and tooling config

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/chilly-moon-pulse.md

@@ -0,0 +1,28 @@
+---
+"@mynameistito/discord-search": major
+---
+
+Set up initial project infrastructure for Discord search CLI tool.
+
+## Tooling & Build
+- Configure TypeScript with tsdown for dual ESM/CJS output
+- Set up Ultracite for linting and formatting
+- Add Lefthook for Git hooks
+- Configure Bun as runtime and package manager
+
+## CI/CD & Automation
+- GitHub Actions workflows: CI, CodeQL, PR triage, release, stale
+- Dependabot for dependency updates
+- Automated PR labeling
+
+## Documentation
+- AGENTS.md with project architecture and conventions
+- Contributing guidelines and code of conduct
+- Security policy and issue templates
+- PR template for standard contributions
+
+## Standards & Quality
+- Railway-oriented programming with better-result
+- Schema-first approach with Zod
+- Tagged error handling patterns
+- Type-first development conventions

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.claude/CLAUDE.md

@@ -0,0 +1,123 @@
+# Ultracite Code Standards
+
+This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.
+
+## Quick Reference
+
+- **Format code**: `bun x ultracite fix`
+- **Check for issues**: `bun x ultracite check`
+- **Diagnose setup**: `bun x ultracite doctor`
+
+Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
+
+---
+
+## Core Principles
+
+Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
+
+### Type Safety & Explicitness
+
+- Use explicit types for function parameters and return values when they enhance clarity
+- Prefer `unknown` over `any` when the type is genuinely unknown
+- Use const assertions (`as const`) for immutable values and literal types
+- Leverage TypeScript's type narrowing instead of type assertions
+- Use meaningful variable names instead of magic numbers - extract constants with descriptive names
+
+### Modern JavaScript/TypeScript
+
+- Use arrow functions for callbacks and short functions
+- Prefer `for...of` loops over `.forEach()` and indexed `for` loops
+- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
+- Prefer template literals over string concatenation
+- Use destructuring for object and array assignments
+- Use `const` by default, `let` only when reassignment is needed, never `var`
+
+### Async & Promises
+
+- Always `await` promises in async functions - don't forget to use the return value
+- Use `async/await` syntax instead of promise chains for better readability
+- Handle errors appropriately in async code with try-catch blocks
+- Don't use async functions as Promise executors
+
+### React & JSX
+
+- Use function components over class components
+- Call hooks at the top level only, never conditionally
+- Specify all dependencies in hook dependency arrays correctly
+- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
+- Nest children between opening and closing tags instead of passing as props
+- Don't define components inside other components
+- Use semantic HTML and ARIA attributes for accessibility:
+  - Provide meaningful alt text for images
+  - Use proper heading hierarchy
+  - Add labels for form inputs
+  - Include keyboard event handlers alongside mouse events
+  - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
+
+### Error Handling & Debugging
+
+- Remove `console.log`, `debugger`, and `alert` statements from production code
+- Throw `Error` objects with descriptive messages, not strings or other values
+- Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them
+- Prefer early returns over nested conditionals for error cases
+
+### Code Organization
+
+- Keep functions focused and under reasonable cognitive complexity limits
+- Extract complex conditions into well-named boolean variables
+- Use early returns to reduce nesting
+- Prefer simple conditionals over nested ternary operators
+- Group related code together and separate concerns
+
+### Security
+
+- Add `rel="noopener"` when using `target="_blank"` on links
+- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
+- Don't use `eval()` or assign directly to `document.cookie`
+- Validate and sanitize user input
+
+### Performance
+
+- Avoid spread syntax in accumulators within loops
+- Use top-level regex literals instead of creating them in loops
+- Prefer specific imports over namespace imports
+- Avoid barrel files (index files that re-export everything)
+- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
+
+### Framework-Specific Guidance
+
+**Next.js:**
+- Use Next.js `<Image>` component for images
+- Use `next/head` or App Router metadata API for head elements
+- Use Server Components for async data fetching instead of async Client Components
+
+**React 19+:**
+- Use ref as a prop instead of `React.forwardRef`
+
+**Solid/Svelte/Vue/Qwik:**
+- Use `class` and `for` attributes (not `className` or `htmlFor`)
+
+---
+
+## Testing
+
+- Write assertions inside `it()` or `test()` blocks
+- Avoid done callbacks in async tests - use async/await instead
+- Don't use `.only` or `.skip` in committed code
+- Keep test suites reasonably flat - avoid excessive `describe` nesting
+
+## When Biome Can't Help
+
+Biome's linter will catch most issues automatically. Focus your attention on:
+
+1. **Business logic correctness** - Biome can't validate your algorithms
+2. **Meaningful naming** - Use descriptive names for functions, variables, and types
+3. **Architecture decisions** - Component structure, data flow, and API design
+4. **Edge cases** - Handle boundary conditions and error states
+5. **User experience** - Accessibility, performance, and usability considerations
+6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
+
+---
+
+Most formatting and common issues are automatically fixed by Biome. Run `bun x ultracite fix` before committing to ensure compliance.

.claude/commands/adopt-better-result.md

@@ -0,0 +1,17 @@
+---
+description: Use better-result-adopt skill for better-result migration/adoption
+---
+
+Load and use the better-result-adopt skill to help with this codebase.
+
+First, invoke the skill:
+
+```
+skill({ name: 'better-result-adopt' })
+```
+
+Then follow the skill instructions.
+
+<user-request>
+$ARGUMENTS
+</user-request>

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "bun fix --skip=correctness/noUnusedImports",
+            "type": "command"
+          }
+        ],
+        "matcher": "Write|Edit"
+      }
+    ]
+  }
+}

.claude/skills/better-result-adopt/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: better-result-adopt
+description: Migrate codebase from try/catch or Promise-based error handling to better-result. Use when adopting Result types, converting thrown exceptions to typed errors, or refactoring existing error handling to railway-oriented programming.
+---
+
+# better-result Adoption
+
+Migrate existing error handling (try/catch, Promise rejections, thrown exceptions) to typed Result-based error handling with better-result.
+
+## When to Use
+
+- Adopting better-result in existing codebase
+- Converting try/catch blocks to Result types
+- Replacing thrown exceptions with typed errors
+- Migrating Promise-based code to Result.tryPromise
+- Introducing railway-oriented programming patterns
+
+## Migration Strategy
+
+### 1. Start at Boundaries
+
+Begin migration at I/O boundaries (API calls, DB queries, file ops) and work inward. Don't attempt full-codebase migration at once.
+
+### 2. Identify Error Categories
+
+Before migrating, categorize errors in target code:
+
+| Category       | Example                | Migration Target                                |
+| -------------- | ---------------------- | ----------------------------------------------- |
+| Domain errors  | NotFound, Validation   | TaggedError + Result.err                        |
+| Infrastructure | Network, DB connection | Result.tryPromise + TaggedError                 |
+| Bugs/defects   | null deref, type error | Let throw (becomes Panic if in Result callback) |
+
+### 3. Migration Order
+
+1. Define TaggedError classes for domain errors
+2. Wrap throwing functions with Result.try/tryPromise
+3. Convert imperative error checks to Result chains
+4. Refactor callbacks to generator composition
+
+## Pattern Transformations
+
+### Try/Catch to Result.try
+
+```typescript
+// BEFORE
+function parseConfig(json: string): Config {
+  try {
+    return JSON.parse(json);
+  } catch (e) {
+    throw new ParseError(e);
+  }
+}
+
+// AFTER
+function parseConfig(json: string): Result<Config, ParseError> {
+  return Result.try({
+    try: () => JSON.parse(json) as Config,
+    catch: (e) => new ParseError({ cause: e, message: `Parse failed: ${e}` }),
+  });
+}
+```
+
+### Async/Await to Result.tryPromise
+
+```typescript
+// BEFORE
+async function fetchUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) throw new ApiError(res.status);
+  return res.json();
+}
+
+// AFTER
+async function fetchUser(id: string): Promise<Result<User, ApiError | UnhandledException>> {
+  return Result.tryPromise({
+    try: async () => {
+      const res = await fetch(`/api/users/${id}`);
+      if (!res.ok) throw new ApiError({ status: res.status, message: `API ${res.status}` });
+      return res.json() as Promise<User>;
+    },
+    catch: (e) => (e instanceof ApiError ? e : new UnhandledException({ cause: e })),
+  });
+}
+```
+
+### Null Checks to Result
+
+```typescript
+// BEFORE
+function findUser(id: string): User | null {
+  return users.find((u) => u.id === id) ?? null;
+}
+// Caller must check: if (user === null) ...
+
+// AFTER
+function findUser(id: string): Result<User, NotFoundError> {
+  const user = users.find((u) => u.id === id);
+  return user
+    ? Result.ok(user)
+    : Result.err(new NotFoundError({ id, message: `User ${id} not found` }));
+}
+// Caller: yield* findUser(id) in Result.gen, or .match()
+```
+
+### Callback Hell to Generator
+
+```typescript
+// BEFORE
+async function processOrder(orderId: string) {
+  try {
+    const order = await fetchOrder(orderId);
+    if (!order) throw new NotFoundError(orderId);
+    const validated = validateOrder(order);
+    if (!validated.ok) throw new ValidationError(validated.errors);
+    const result = await submitOrder(validated.data);
+    return result;
+  } catch (e) {
+    if (e instanceof NotFoundError) return { error: "not_found" };
+    if (e instanceof ValidationError) return { error: "invalid" };
+    throw e;
+  }
+}
+
+// AFTER
+async function processOrder(orderId: string): Promise<Result<OrderResult, OrderError>> {
+  return Result.gen(async function* () {
+    const order = yield* Result.await(fetchOrder(orderId));
+    const validated = yield* validateOrder(order);
+    const result = yield* Result.await(submitOrder(validated));
+    return Result.ok(result);
+  });
+}
+// Error type is union of all yielded errors
+```
+
+## Defining TaggedErrors
+
+See [references/tagged-errors.md](references/tagged-errors.md) for TaggedError patterns.
+
+## Workflow
+
+1. **Check for source reference**: Look for `opensrc/` directory - if present, read the better-result source code for implementation details and patterns
+2. **Audit**: Find try/catch, Promise.catch, thrown errors in target module
+3. **Define errors**: Create TaggedError classes for domain errors
+4. **Wrap boundaries**: Use Result.try/tryPromise at I/O points
+5. **Chain operations**: Convert if/else error checks to .andThen or Result.gen
+6. **Update signatures**: Change return types to Result<T, E>
+7. **Update callers**: Propagate Result handling up call stack
+8. **Test**: Verify error paths with .match or type narrowing
+
+## Common Pitfalls
+
+- **Over-wrapping**: Don't wrap every function. Start at boundaries, propagate inward.
+- **Losing error info**: Always include cause/context in TaggedError constructors.
+- **Mixing paradigms**: Once a module returns Result, callers should too (or explicitly .unwrap).
+- **Ignoring Panic**: Callbacks that throw become Panic. Fix the bug, don't catch Panic.
+
+## References
+
+- [TaggedError Patterns](references/tagged-errors.md) - Defining and matching typed errors
+- `opensrc/` directory (if present) - Full better-result source code for deeper context