···11+anartia is a JavaScript-optional public web frontend for Bluesky, built with SvelteKit and Vite,
22+deployed to Cloudflare Workers.
33+44+## development notes
55+66+### project management
77+88+- Node.js and pnpm is managed by mise
99+- install dependencies with `pnpm install`
1010+- run dev server with `pnpm dev`
1111+- build with `pnpm build`
1212+- preview production build with `pnpm preview`
1313+- format via `pnpm format` (Prettier)
1414+- lint via `pnpm lint` (Prettier check)
1515+- typecheck via `pnpm check` (svelte-check)
1616+- check `pnpm view <package>` before adding a new dependency
1717+1818+### code writing
1919+2020+- new files should be in kebab-case
2121+- use tabs for indentation, spaces allowed for diagrams in comments
2222+- use single quotes for strings; use template literals for localization strings (user-facing
2323+ strings, error messages)
2424+- add trailing commas
2525+- prefer arrow functions, but use regular methods in classes unless arrow functions are necessary
2626+ (e.g., when passing the method as a callback that needs `this` binding)
2727+- use braces for control statements, even single-line bodies
2828+- use bare blocks `{ }` to group related code and limit variable scope
2929+- avoid barrel exports (index files that re-export from other modules); import directly from source
3030+- use `// #region <name>` and `// #endregion` to denote regions when a file needs to contain a lot
3131+ of code
3232+- a parameter should be optional only when callers genuinely split between passing a value and
3333+ relying on the default; if every caller passes a value, make it required; if no caller would ever
3434+ change it, it should not be a parameter at all
3535+- avoid optional parameters that change behavioral modes or make the function do different things
3636+ based on presence/absence; prefer a separate function with a clearer name instead
3737+- avoid type assertions (`as Type`, `as const`) unless TypeScript actually errors without them; when
3838+ it does error, prefer finding a solution that satisfies the type system naturally before resorting
3939+ to an assertion
4040+4141+### documentation
4242+4343+- documentations include README, code comments, commit messages
4444+- any writing should be in lowercase, except for proper nouns, acronyms and 'I'; this does not apply
4545+ to public-facing interfaces like web UI
4646+- only comment non-trivial code, focusing on _why_ rather than _what_
4747+- write comments and JSDoc in lowercase (except proper nouns, acronyms, and 'I')
4848+- add JSDoc comments to new publicly exported functions, methods, classes, fields, and enums
4949+- JSDoc should include proper annotations:
5050+ - use `@param` for parameters (no dashes after param names)
5151+ - use `@returns` for return values
5252+ - use `@throws` for exceptions when applicable
5353+ - keep descriptions concise but informative
5454+5555+### agentic coding
5656+5757+- `.research/` directory in the project root serves as a workspace for temporary experiments,
5858+ analysis, and planning materials. create if not present (it's gitignored). this directory may
5959+ contain cloned repositories or other reference materials that can help inform implementation
6060+ decisions
6161+- this document is intentionally incomplete; discover everything else in the repo
6262+- don't make assumptions or speculate about code, plans, or requirements without exploring first;
6363+ pause and ask for clarification when you're still unsure after looking into it
6464+- in plan mode, present the plan for review before exiting to allow for feedback or follow-up
6565+ questions
6666+- when debugging problems, isolate the root cause first before attempting fixes: add logging,
6767+ reproduce the issue, narrow down the scope, and confirm the exact source of the problem
6868+6969+### Claude Code-specific
7070+7171+- Explore subagent may not be accurate; verify findings as needed
7272+- never spawn subagents to read and return file contents; read files directly in the main context.
7373+ subagents should perform searches or answer specific questions, not act as file I/O proxies
7474+7575+### external repository research
7676+7777+use `@oomfware/cgr` to ask questions about external repositories:
7878+7979+```
8080+npx @oomfware/cgr ask [options] <repo>[#branch] <question>
8181+8282+options:
8383+ -m, --model <model> model to use: opus, sonnet, haiku (default: haiku)
8484+ -d, --deep clone full history (enables git log/blame/show)
8585+ -w, --with <repo> additional repository to include, supports #branch (repeatable)
8686+```
8787+8888+useful repositories for development:
8989+9090+- `github.com/bluesky-social/atproto` for AT Protocol reference implementation, lexicons, XRPC
9191+- `github.com/bluesky-social/social-app` for Bluesky app patterns, API usage examples
9292+- `github.com/bluesky-social/proposals` for AT Protocol proposals and specifications
9393+- `github.com/bluesky-social/atproto-website` for AT Protocol spec documentation
9494+- `github.com/mary-ext/atcute` for the AT Protocol client library used in this project
9595+- `github.com/sveltejs/kit` for SvelteKit framework internals and patterns
9696+- `github.com/sveltejs/svelte` for Svelte 5 runes, components, and runtime
9797+9898+broad questions work for getting oriented; detailed questions get precise answers. include
9999+file/folder paths when you know them, and reference details from previous answers in follow-ups.
100100+101101+run `npx @oomfware/cgr --help` for more options.