Update docs (#1695)

Author: skyfallwastaken

.agents/setup

@@ -27,15 +27,26 @@ if [ -z "$gh_version" ] || ! dpkg --compare-versions "$gh_version" ge "$gh_min_v
   sudo apt-get install -y gh
 fi
 
+docker_packages=()
 if ! command -v docker >/dev/null 2>&1; then
-  echo "==> Installing Docker and Docker Compose"
+  docker_packages+=(docker-ce docker-ce-cli containerd.io)
+fi
+if ! sudo docker buildx version >/dev/null 2>&1; then
+  docker_packages+=(docker-buildx-plugin)
+fi
+if ! sudo docker compose version >/dev/null 2>&1; then
+  docker_packages+=(docker-compose-plugin)
+fi
+
+if [ "${#docker_packages[@]}" -gt 0 ]; then
+  echo "==> Installing missing Docker components: ${docker_packages[*]}"
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |
     sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
   sudo apt-get update
-  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+  sudo apt-get install -y "${docker_packages[@]}"
 fi
 
 setup_user="$(id -un)"
@@ -65,7 +76,7 @@ if [ ! -f .env ]; then
   cp -- .env.example .env
 fi
 
-container_fingerprint="$(fingerprint Dockerfile.dev docker-compose.yml entrypoint.dev.sh Gemfile Gemfile.lock package.json bun.lock)"
+container_fingerprint="$(fingerprint Dockerfile.dev docker-compose.yml entrypoint.dev.sh Gemfile Gemfile.lock package.json bun.lock bunfig.toml)"
 if cache_matches containers "$container_fingerprint"; then
   echo "==> Starting existing development containers"
   sudo docker compose up -d
@@ -82,7 +93,7 @@ sudo docker compose exec -T web sh -c '
     git config --global --add safe.directory "$repo_root"
 '
 
-assets_fingerprint="$(fingerprint app/javascript app/assets/tailwind config/routes.rb config/vite.json config/initializers/js_from_routes.rb vite.config.ts svelte.config.js tsconfig.json tsconfig.svelte-check.json package.json bun.lock)"
+assets_fingerprint="$(fingerprint app/javascript app/assets/tailwind config/routes.rb config/vite.json config/initializers/js_from_routes.rb vite.config.ts svelte.config.js tsconfig.json tsconfig.svelte-check.json package.json bun.lock bunfig.toml)"
 if cache_matches assets "$assets_fingerprint" && [ -f public/vite-dev/.vite/manifest.json ]; then
   echo "==> Vite client assets are current"
 else

DEVELOPMENT.md

@@ -21,7 +21,6 @@ Edit your `.env` file to include the following:
 ```env
 # Database configurations - these work with the Docker setup
 DATABASE_URL=postgres://postgres:secureorpheus123@db:5432/app_development
-SAILORS_LOG_DATABASE_URL=postgres://postgres:secureorpheus123@db:5432/app_development
 
 # Generate these with `rails secret` or use these for development
 SECRET_KEY_BASE=alallalalallalalallalalalladlalllalal
@@ -100,6 +99,14 @@ To run all CI checks locally, you can run:
 docker compose exec web bin/ci
 ```
 
+Bun uses the isolated linker configured in `bunfig.toml`, matching the production Docker build. The development image also copies this configuration when installing dependencies. If you have an existing hoisted install, clear the contents of the `node_modules` volume and Blume's generated cache, then reinstall before running CI:
+
+```bash
+docker compose exec web sh -c 'find node_modules -mindepth 1 -delete && rm -rf .blume && bun install --frozen-lockfile'
+```
+
+This avoids mixing Sharp's native libraries with the separate libvips version used by Ruby in the production image.
+
 _Make sure these actually pass before making a PR!_
 
 ## Migrations

Dockerfile.dev

@@ -26,7 +26,7 @@ RUN curl -fsSL https://bun.sh/install | bash && \
 WORKDIR /app
 
 # Install npm dependencies for Vite.
-COPY package.json bun.lock ./
+COPY package.json bun.lock bunfig.toml ./
 RUN bun install && \
     bun x playwright install --with-deps --only-shell chromium && \
     rm -rf /var/lib/apt/lists/* /var/cache/apt/archives

bunfig.toml

@@ -1,4 +1,8 @@
 [install]
+# Match production: keep Sharp's native libraries separate from the libvips
+# version installed at the root for Ruby Vips in the Docker image.
+linker = "isolated"
+
 # Only install package versions published at least 1 day ago
 # (cough cough axios RAT...)
 minimumReleaseAge = 86400 # seconds

config/database.yml

@@ -9,11 +9,6 @@ development:
     encoding: unicode
     pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
     url: <%= ENV['DATABASE_URL'] %>
-  sailors_log:
-    adapter: postgresql
-    encoding: unicode
-    url: <%= ENV['SAILORS_LOG_DATABASE_URL'] %>
-    replica: true
 
 # Warning: The database defined as "test" will be erased and
 # re-generated from your development database when you run "rake".
@@ -24,11 +19,6 @@ test:
     adapter: postgresql
     database: app_test
     url: <%= ENV['TEST_DATABASE_URL'] %>
-  sailors_log:
-    adapter: postgresql
-    database: app_test
-    url: <%= ENV['TEST_DATABASE_URL'] %>
-    replica: true
 
 # Store production database in the storage/ directory, which by default
 # is mounted as a persistent Docker volume in config/deploy.yml.
@@ -39,11 +29,6 @@ production:
     encoding: unicode
     pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 16 }.to_i + 8 %> # Web threads + 8 GoodJob threads
     url: <%= ENV['POOL_DATABASE_URL'] %>
-  sailors_log:
-    adapter: postgresql
-    encoding: unicode
-    url: <%= ENV['SAILORS_LOG_DATABASE_URL'] %>
-    replica: true
   cache:
     <<: *default
     adapter: postgresql

docs/getting-started/quick-start.mdx

@@ -12,7 +12,8 @@ Get up and running with Hackatime in under 5 minutes! Start tracking your coding
 
 Visit [hackatime.hackclub.com](https://hackatime.hackclub.com) and sign up using:
 
-- Your Hack Club Slack account (recommended)
+- **Sign in with Hack Club** using your Hack Club Account
+- Your Hack Club Slack account
 - Email address
 
 ## Step 2: Run automated setup
@@ -96,7 +97,7 @@ Just run the automated setup script on the [Hackatime Setup Page](https://hackat
     Hackatime is free, open source, privacy-focused, and includes unique features like leaderboards for Hack Club members.
   </AccordionItem>
   <AccordionItem title="Can I import my existing WakaTime data?">
-    Currently, data import is not supported, but you can start fresh with Hackatime while keeping your WakaTime account.
+    Yes! Open [Settings → Imports & Exports](https://hackatime.hackclub.com/my/settings/imports_exports), choose **WakaTime** under **Imports**, and enter your WakaTime API key to request a one-time heartbeat dump. You can follow the import's progress on that page.
   </AccordionItem>
   <AccordionItem title="Is my code data secure?">
     Hackatime only tracks metadata (file names, languages, project names) - never your actual code content. All data is encrypted in transit.

docs/oauth/oauth-apps.md

@@ -26,7 +26,7 @@ Scopes control what data your app can access. It's a good idea to only request t
 |-------|-------------|-------------------|
 | `profile` | Access basic profile information (user ID, email addresses, Slack ID, GitHub username, trust factor) | Yes |
 | `read` | View basic info about the user's Hackatime account | No |
-| `admin` | Access the [Admin API](#admin-api-access) on the authorizing admin's behalf. | No |
+| `admin` | Access the [Admin API](#admin-api-access) on the authorizing user's behalf, subject to their role permissions. | No |
 
 If you don't specify any scopes, only the `profile` scope is granted.
 
@@ -39,6 +39,7 @@ scope=profile+read
 ### Admin scope restrictions
 
 - Only **admin+** users (`admin`, `superadmin`, `ultraadmin`) can attach the `admin` scope to an OAuth application.
+- **Viewers and admin+ users** (`viewer`, `admin`, `superadmin`, `ultraadmin`) can authorize an approved application requesting the `admin` scope. The token does not grant permissions beyond the authorizing user's role.
 - Apps with the `admin` scope must be **confidential** (server-side clients that can keep a secret).
 - **This scope requires approval from Hack Club HQ to use.** It won't work if you try to use it without permission!
 
@@ -107,7 +108,7 @@ POST https://hackatime.hackclub.com/oauth/token
 {
   "access_token": "abc123...",
   "token_type": "Bearer",
-  "expires_in": 504576000,
+  "expires_in": 504911232,
   "scope": "profile read",
   "created_at": 1700000000
 }
@@ -236,6 +237,14 @@ Returns the user's most recent heartbeat.
 }
 ```
 
+If the user has no heartbeats (excluding setup test entries), the endpoint returns **200 OK** with:
+
+```json
+{
+  "heartbeat": null
+}
+```
+
 ### GET /api/v1/authenticated/api_keys
 
 Returns the user's Hackatime API key (creates one if none exists).