feat: enhance documentation and add new features for Afilmory

- Introduced a comprehensive `DEVELOPMENT.md` guide for contributors and self-hosters, detailing workspace layout and common commands.
- Updated `README.md` to include links to the new development guide and improved deployment instructions.
- Added new documentation files covering architecture, builder pipeline, configuration, and deployment strategies.
- Implemented new storage provider documentation for Backblaze B2, Eagle, GitHub, and local storage options.
- Enhanced the UI components with new features, including a navigation context and improved theme handling.
- Removed outdated GitHub Action deployment documentation.

Signed-off-by: Innei <[email protected]>

Author: Innei

DEVELOPMENT.md

@@ -0,0 +1,124 @@
+# Development Guide
+
+This document is for contributors and self-hosters who want to customize or run Afilmory from source.
+
+## Workspace Layout
+
+- `apps/web`: React + Vite SPA that consumes `photos-manifest.json` and generated thumbnails under `apps/web/public`.
+- `apps/ssr`: Next.js wrapper that injects the manifest for SEO/OG and proxies SPA assets.
+- `packages/builder`: Photo pipeline that syncs sources → processes images → writes manifest/thumbnails into the SPA.
+- `config.json` + `site.config.ts`: Presentation/content config merged at runtime for both SPA and SSR.
+- `builder.config.ts`: Builder pipeline config (storage, concurrency, repo sync, plugins).
+
+## Quick Start (from source)
+
+1. Install dependencies
+
+```bash
+pnpm install
+```
+
+2. Copy configs and fill values
+
+```bash
+cp config.example.json config.json
+cp builder.config.default.ts builder.config.ts
+```
+
+3. Environment variables (`.env`)
+
+- Storage: `S3_REGION`, `S3_ENDPOINT`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_PREFIX`, `S3_CUSTOM_DOMAIN`, `S3_EXCLUDE_REGEX`
+- Repo sync (optional): `GIT_TOKEN`, `BUILDER_REPO_URL`, `BUILDER_REPO_BRANCH`
+
+4. Build/update manifest and thumbnails (writes to `apps/web/src/data/photos-manifest.json` and `apps/web/public`)
+
+```bash
+pnpm run build:manifest             # incremental
+pnpm run build:manifest -- --force # full rebuild
+```
+
+5. Run the app
+
+```bash
+pnpm dev              # SPA + SSR
+pnpm --filter web dev # SPA only
+pnpm --filter @afilmory/ssr dev # SSR wrapper only
+```
+
+## Builder Configuration (`builder.config.ts`)
+
+The builder uses `defineBuilderConfig` from `@afilmory/builder`. `builder.config.default.ts` shows the recommended shape:
+
+```ts
+import os from 'node:os'
+import { defineBuilderConfig, githubRepoSyncPlugin } from '@afilmory/builder'
+import { env } from './env.js'
+
+export default defineBuilderConfig(() => ({
+  storage: {
+    // Switch to { provider: 'local', basePath, baseUrl } for local-only testing.
+    provider: 's3',
+    bucket: env.S3_BUCKET_NAME,
+    region: env.S3_REGION,
+    endpoint: env.S3_ENDPOINT,
+    accessKeyId: env.S3_ACCESS_KEY_ID,
+    secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+    prefix: env.S3_PREFIX,
+    customDomain: env.S3_CUSTOM_DOMAIN,
+    excludeRegex: env.S3_EXCLUDE_REGEX,
+    downloadConcurrency: 16,
+  },
+  system: {
+    processing: { defaultConcurrency: 10, enableLivePhotoDetection: true, digestSuffixLength: 0 },
+    observability: {
+      showProgress: true,
+      showDetailedStats: true,
+      logging: { verbose: false, level: 'info', outputToFile: false },
+      performance: {
+        worker: { workerCount: os.cpus().length * 2, timeout: 30_000, useClusterMode: true, workerConcurrency: 2 },
+      },
+    },
+  },
+  plugins: [
+    githubRepoSyncPlugin({
+      repo: {
+        enable: false,
+        url: process.env.BUILDER_REPO_URL ?? '',
+        token: env.GIT_TOKEN,
+        branch: process.env.BUILDER_REPO_BRANCH ?? 'main',
+      },
+    }),
+  ],
+}))
+```
+
+Notes:
+
+- B2/GitHub storage are also supported (see comments in `builder.config.ts`).
+- Outputs land in `apps/web/public/thumbnails` and `apps/web/src/data/photos-manifest.json`.
+
+## Site Presentation Config (`config.json`)
+
+`config.json` merges into `site.config.ts` for both SPA and SSR:
+
+- `name` / `title` / `description` / `url` / `accentColor`
+- `author`: `{ name, url, avatar }`
+- `social`: `{ github?, twitter?, rss? }`
+- `feed`: supports `folo.challenge.feedId` and `userId`
+- `map`: map providers, e.g. `["maplibre"]`
+- `mapStyle`: `builtin` or provider-specific style
+- `mapProjection`: `globe` or `mercator`
+
+## Common Commands
+
+```bash
+# Lint and format
+pnpm lint
+pnpm format
+
+# Type check (web)
+pnpm --filter web type-check
+
+# Build production
+pnpm build
+```

README.md

@@ -77,94 +77,19 @@ Designed with adapter pattern, supporting multiple storage backends:
 - **Eagle Storage** - Using Eagle app library as image storage
 - **Local File System** - Local storage for development and testing
 
-## 🚀 Quick Start
+## 🚀 Self-Host
 
-### Docker Deployment
+### Option A: Docker (recommended)
 
-[Docker Deployment](https://github.com/Afilmory/docker)
+[Docker deployment guide](https://github.com/Afilmory/docker) ships prebuilt images with minimal setup.
 
-## ⚙️ Configuration Options
+### Option B: Manual install
 
-#### Remote Repository Configuration (`repo`)
+1. Copy `config.example.json` to `config.json` and fill in your site name, description, and social links.
+2. Prepare access to your photo storage (S3/B2/GitHub/local). The builder will read photos and generate thumbnails plus `photos-manifest.json`.
+3. Run the builder to generate assets, then start the site.
 
-To achieve incremental builds in CI, it is necessary to configure a cache repository, which will pull the cache before each build and upload the build results after the build.
-
-```json
-{
-  "repo": {
-    "enable": true,
-    "url": "https://github.com/username/gallery-assets"
-  }
-}
-```
-
-This will automatically pull resources from the remote repository, avoiding rebuilds each time.
-
-**In order to achieve uploading to the git repository, you need to provide a `GIT_TOKEN` and write it in the `.env` file.**
-
-#### Storage Configuration (`storage`)
-
-- `provider`: Storage provider (`s3` | `github`)
-- `bucket`: S3 bucket name
-- `region`: S3 region
-- `endpoint`: S3 endpoint (optional)
-- `prefix`: File prefix
-- `customDomain`: Custom domain
-- `excludeRegex`: Regular expression to exclude files (optional)
-
-#### System Processing (`system.processing`)
-
-- `defaultConcurrency`: Default concurrency
-- `digestSuffixLength`: The length of the SHA-256 digest appended to the photo ID
-- `enableLivePhotoDetection`: Enable Live Photo detection
-- `supportedFormats`: Optional allowlist of file extensions to process
-
-#### System Observability (`system.observability`)
-
-- `showProgress`: Show build progress
-- `showDetailedStats`: Show detailed statistics
-- `logging.verbose`: Verbose logging
-- `logging.level`: Log level (`info` | `warn` | `error` | `debug`)
-- `logging.outputToFile`: Output to file
-- `performance.worker.workerCount`: Number of worker processes
-- `performance.worker.timeout`: Worker timeout (milliseconds)
-- `performance.worker.useClusterMode`: Enable cluster mode
-
-## 📋 CLI Commands
-
-### Build Commands
-
-```bash
-# View help
-pnpm run build:manifest -- --help
-
-# Incremental update (default)
-pnpm run build:manifest
-
-# Force full update
-pnpm run build:manifest -- --force
-
-# Only regenerate thumbnails
-pnpm run build:manifest -- --force-thumbnails
-
-# Only regenerate manifest
-pnpm run build:manifest -- --force-manifest
-```
-
-### Development Commands
-
-```bash
-# Start development server
-pnpm dev
-
-# Build production version
-pnpm build
-```
-
-### Notes
-
-- Ensure your S3 bucket already contains photo files
-- If using remote repository, configure `builder.config.ts` first
+Looking for developer commands, environment variables, and builder config details? See `DEVELOPMENT.md`.
 
 ## 🔧 Advanced Usage
 
@@ -205,7 +130,7 @@ Attribution Network License (ANL) v1.0 © 2025 Afilmory Team. See [LICENSE](LICE
 
 ## 🔗 Related Links
 
-- [Live Demo](https://gallery.innei.in)
+- [Live Demo](https://afilmory.innei.in)
 - [Personal Website](https://innei.in)
 - [GitHub](https://github.com/innei)