More details on docs

Dockerfile

···
+#Had problems with pnpm and sqlite, so just using npm. bit longer but gets the job done.
+
 FROM node:24-slim AS builder
 WORKDIR /app
 

LICENSE.md

···
+MIT License
+
+Copyright (c) 2025 Bailey Townsend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

···
 
 ## Features
 - OAuth client configured from `.env` variables
-  - `DEV=true` allows local development, do not need a public url
-  - removing `DEV=true` and setting `OAUTH_DOMAIN` is production and requires a public url like [demo.atpoke.xyz](https://demo.atpoke.xyz)
-  - Setting `OAUTH_JWK` allows for the confidential client that lasts much longer (forever if you refresh the tokens, 180 for indivudal refresh tokens). Can get a value for it from running `node ./bin/gen-jwk.js`
 - Server side sessions and automatic loading of the atproto client from `event.locals.atpAgent` on server side components.
 - Examples on how to create atproto records with [pokes or making a Bluesky post](./src/routes/demo/+page.server.ts)
 - Examples showing how to use [microcosm.blue](https://microcosm.blue/) tooling for an appview like experince without the appview.
···
   - Find the [handles from the did](./src/routes/demo/+page.svelte) easily with [slingshot](https://slingshot.microcosm.blue/)
 
 ## Dev Setup
-1. Copy [.env.example](.env.example) to [.env](.env), .env.example is dev settings
+Should work with any package manager if you prefer to use another. But these are directions for [pnpm](https://pnpm.io/)
+
+1. Copy [.env.example](.env.example) to [.env](.env), .env.example is the default dev settings
 2. `pnpm install`
 3. May need to run `pnpm approve-builds` for the build scripts for sqlite
 4. `pnpm run dev` or `pnpm run dev:logging` with [pino-pretty](https://github.com/pinojs/pino-pretty) for pretty logging
 
 > If you are running locally on a different port than `5173` or something else odd can set `OAUTH_DOMAIN` .env to the domain and port. Just make sure to use either `127.0.0.1` or `[::1]`(ipv6) for oauth to work for local development.
 
+## Implementation details
+Details on some of the implementation details that you will most likely want to edit when creating your own project.
+
+### How to configure OAuth
+OAuth *should* Already be figured out for you with everything being configured from the environment variables without having to modify any code.
+
+> All atproto actions taken for the user happen server side, so we can take advantage of the confidential client and longer session lifetimes.
+
+## Types of OAuth clients
+- Development local - Set `DEV=true` in `.env` to use a local development client. This is a special client just for development does not require having a public url. As outlined [here](https://atproto.com/specs/oauth#localhost-client-development). This is the default from copying the [.env.example](.env.example)
+- Production Public – Remove the `DEV=true`, Set `OAUTH_DOMAIN` to your publicliy accessible domain([demo.atpoke.xyz](https://demo.atpoke.xyz) in `.env` to use a production public client. These have a lower atproto oauth session lifetime which is limited to 2 weeks. 
+- Production Confidential - Follow `Production Public` and set `OAUTH_JWK` to the value from `node ./bin/gen-jwk.js`. **These are cryptographic signing keys and should be kept secret and private**. These have the longest session lifetime of 180 days for refresh tokens, or indefinitely if refreshed till, pending revocation or jwk rotation.
+
+Most likely in production you are going to want the Confidential client for the longest lifetime.
+The cookie session lifetime is less, so this could expire before the atproto session lifetime. This can be configured at [./src/lib/server/session.ts](./src/lib/server/session.ts), default is 30 days and resets for every logged-in web action. Can read more on atproto clients with [Client type details](https://atproto.com/specs/oauth#types-of-clients) and [session lifetime details](https://atproto.com/specs/oauth#tokens-and-session-lifetime)
+
+## OAuth scopes 
+OAuth scopes are permissions to the user's repo you are requesting. You can read more on them and learn the different ones on [atproto.com/specs/permission](https://atproto.com/specs/permission) 
+
+This demo application only requires the access to the lexicons it needs with default scopes of `atproto repo:app.bsky.feed.post?action=create repo:xyz.atpoke.graph.poke`. This can be changed by setting the `OAUTH_SCOPES` environment variable. For development or full access to a user's repo you are probably looking for `atproto transition:generic`
+![oauth scopes](.tangled/images/oauth-no-scope.png)
+
+> You may find as you're trying out new scopes that the OAuth screen may not reflect what you've requested. This is because the PDS can cache those. [Docs say this can be anywehre from 15-30mins](https://atproto.com/specs/permission#resolution-and-caching)
+
+## OAuth Branding
+There are a couple of other odds and ends you can set for OAuth to customize the branding. This mostly shows up on `yourpds.com/account` for now, but it is a standard and more may adpot it. Will be taking the [docs definitions](https://atproto.com/specs/oauth#client-id-metadata-document) for each.
+
+- `OAUTH_CLIENT_NAME` - (string, optional): human-readable name of the client
+- `OAUTH_LOGO_URI` - (string, optional): URL to client logo. Only https: URIs are allowed.
+- `OAUTH_TOS_URI` - (string, optional): URL to human-readable terms of service (ToS) for the client. Only https: URIs are allowed.
+- `OAUTH_POLICY_URI` - (string, optional): URL to human-readable privacy policy for the client. Only https: URIs are allowed.
+
+### Database
+This project uses [drizzle ORM](https://orm.drizzle.team/) with the sqlite adapter to make it easy to run locally and get started. This is used for the session store for the server and atproto. This will work for production as well and can build on it as is, but if you want to change out the database layer it should not be too bad since there's not a ton of db queries right now. This is a quick overview of that layer.
+
+- [./src/lib/server/db/index.ts](./src/lib/server/db/index.ts). This sets up the DB
+- [./src/lib/server/db/schema.ts](./src/lib/server/db/schema.ts). This is your database schema.
+- [./src/lib/server/cache.ts](./src/lib/server/cache.ts). This is an abstracted key/value cache that the [@atproto/oauth-client-node](https://www.npmjs.com/package/@atproto/oauth-client-node?activeTab=readme) uses to store state and sessions.
+- [./src/lib/server/session.ts](./src/lib/server/session.ts). This is the server side session store that is tied to the cookie session.
+- A tiny job runs at [./src/hooks.server.ts](./src/hooks.server.ts) that clears the atproto state store, and runs migrations on startup. If you change from a node server adapter may have to change this as well.
+- Will most likely need to change out some settings in [drizzle.config.ts](drizzle.config.ts)
+- Delete the contents in [drizzle](drizzle) and run `pnpm run db:generate` to generate new migration files for the new adapter.
+
+
+
+### Other production considerations
+I did not find a great way to run a "sidecar process" with SvelteKit, and by that I mean a [Jetstream listener](https://docs.bsky.app/blog/jetstream) that runs alongside the SvelteKit application. If you are needing to listen to the firehose or jetstream to get real time records being created, I'd recommend changing out the database layered to something not embedded, then run a separate container (or process) with a node script running in a loop to get that data. [@atcute/jetstream](https://tangled.org/mary.my.id/atcute/tree/trunk/packages/clients/jetstream) is a great way to do this in TypeScript. 
+For an overview of what that gets you and why you would want that I'd recommend checking out the quick start guide [Statusphere](https://atproto.com/guides/applications) to see how it is used there and why.
+
+
 ## Production
 
 > Sign up for Railway with my referral code [z49xDi](https://railway.com?referralCode=z49xDi) to get $20 in credits, and if you spend anything, I get 15% in credits. 
···
 1. Install the railway cli ([directions here](https://docs.railway.com/guides/cli#installing-the-cli))
 2. Login with `railway login`
 3. Create a new project with `railway init`, set your project name
-4. Deploy your webapp with `railway up`, this will create a new deployment. This will crash on the first run since we still have some changes to make. This is what uploads your code to railway. That is expected since we don't have a volume and our variables yet.
-![crash](.tangled/images/crash.png)
+4. Deploy your webapp with `railway up`, this will create a new deployment. This will crash on the first run since we still have some changes to make. That is expected since we don't have a volume and our variables yet. This is what actually uploads your code to railway via the [dockerfile](Dockerfile).
+   ![crash](.tangled/images/crash.png)
 5. `railway service` select the service you deployed earlier, name is most likely the same as the project name.
 6. Run `railway volume add -m /app_data` to create a persistent volume for the sqlite database.
 7. If you do not already have your project dashboard open you can open it with `railway open`, this opens it in a web browser.

src/lib/server/atproto/client.ts

···
                     token_endpoint_auth_method: isConfidential ? 'private_key_jwt' : 'none',
                     dpop_bound_access_tokens: true,
                     jwks_uri: isConfidential ? `${rootUrl}/.well-known/jwks.json` : undefined,
-                    token_endpoint_auth_signing_alg: isConfidential ? pk?.alg : undefined
+                    token_endpoint_auth_signing_alg: isConfidential ? pk?.alg : undefined,
+                    tos_uri: env.OAUTH_TOS_URI,
+                    policy_uri: env.OAUTH_POLICY_URI,
                 };
 
             return new NodeOAuthClient({

src/routes/+layout.svelte

···
 
 <svelte:head>
 	<link rel="icon" href={favicon} />
+	<title>SvelteKit Atproto Demo</title>
+	<meta property="og:title" content="SvelteKit Atproto Demo" />
+	<meta property="og:description"
+		  content="A demo application with pokes." />
+	<meta property="description"
+		  content="A demo application with pokes." />
 </svelte:head>
 
 {#if data.session}

src/routes/+page.svelte

···
 <div>
     <h1>SvelteKit ATProtocol OAuth template</h1>
     <h3>A build your own ATProto adventure</h3>
-    <p> It's up to you on what this project should be and what it looks like. This is mostly just a technical preview showing a demo of what the application looks like and how it works. But if you <a href="/login">Login</a> you can poke people or see who poked you, so there's that at least.</p>
+    <p> It's up to you on what this project should be and what it looks like. Fork the project on <a href="https://tangled.org/baileytownsend.dev/atproto-sveltekit-template">tangled.org</a> to make it your own. This web hosted version is mostly just a technical preview showing a demo of what the application looks like and how it works, not a lot here, or even styling that's up to you, not me. But if you <a href="/login">Login</a> you can poke people or see who poked you, so there's that at least.</p>
     <h3>A bare minimal SvelteKit demo that...</h3>
     <ul>
         <li>Can have local dev oauth with setting the <code>.env</code> variable <code>DEV=true</code></li>
···
         <li>A persistent session store using <a href="https://orm.drizzle.team/">drizzle</a> with sqlite</li>
         <li>A docker compose and documentation on how to deploy to <a href="https://railway.com/">railway</a></li>
         <li><a href="/demo">An example page using the atproto Agent where you can make a post or poke someone</a> </li>
+        <li>Uses <a href="https://microcosm.blue" class="link"><span
+                style="color: rgb(243, 150, 169);">m</span><span style="color: rgb(244, 156, 92);">i</span><span
+                style="color: rgb(199, 176, 76);">c</span><span style="color: rgb(146, 190, 76);">r</span><span
+                style="color: rgb(78, 198, 136);">o</span><span style="color: rgb(81, 194, 182);">c</span><span
+                style="color: rgb(84, 190, 215);">o</span><span style="color: rgb(143, 177, 241);">s</span><span
+                style="color: rgb(206, 157, 241);">m</span></a> for demoing some AppView-less features you can do, like seeing who has poked you without a backend.
+        </li>
         <li>Source code can be found on <a href="https://tangled.org/baileytownsend.dev/atproto-sveltekit-template">tangled.org</a> </li>
     </ul>
     <br/>

src/routes/demo/+page.server.ts

···
                     text: rt.text,
                     facets: rt.facets,
                     createdAt: new Date().toISOString(),
+                    //This sets the language of the post. Want to most likely get it from a locale of the browser
+                    //cheating here and using english since the rest of the documentations in english and this is a demo
+                    langs: [
+                        'en'
+                    ]
                 };
 
                 const result = await agent.com.atproto.repo.createRecord({