@hiai-gg/hiai-docs 0.0.1

package/.all-contributorsrc

@@ -0,0 +1,18 @@
+{
+  "projectName": "hiai-docs",
+  "projectOwner": "hiai-gg",
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "files": ["README.md"],
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "vgalibov",
+      "name": "vgalibov",
+      "avatar_url": "https://github.com/vgalibov.png",
+      "profile": "https://github.com/vgalibov",
+      "contributions": ["code", "doc", "infra", "review", "maintenance"]
+    }
+  ],
+  "contributorsPerLine": 7
+}

package/.claude/settings.local.json

@@ -0,0 +1,61 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git mv *)",
+      "Bash(echo \"rm exit: $?\")",
+      "Bash(sudo rm -rf .svelte-kit/types)",
+      "Bash(echo \"exit $?\")",
+      "Bash(docker exec *)",
+      "Bash(curl -fsS -o /dev/null -w \"frontend:%{http_code}\\\\n\" http://localhost:50701/)",
+      "Bash(curl -fsS -o /dev/null -w \"api-health:%{http_code}\\\\n\" http://localhost:50700/api/health)",
+      "Bash(bunx @biomejs/biome check --max-diagnostics=none 'frontend/src/routes/\\(app\\)/+page.svelte' 'frontend/src/routes/\\(app\\)/docs/[id]/+page.svelte' frontend/src/lib/components/sidebar/TagList.svelte frontend/src/lib/components/sidebar/RecentDocs.svelte frontend/src/lib/stores/tag-store.svelte.ts frontend/src/lib/components/editor/EditorToolbar.svelte frontend/src/lib/components/editor/LinkDialog.svelte frontend/src/lib/api/settings.ts backend/src/api/routes/attachments.ts backend/src/api/routes/documents.ts)",
+      "mcp__plugin_playwright_playwright__browser_navigate",
+      "Bash(timeout 300 bunx playwright install chromium)",
+      "Bash(timeout 300 bunx playwright install chrome)",
+      "Bash(curl -s -o /dev/null -w \"GET /api/health -> %{http_code}\\\\n\" http://localhost:50700/api/health)",
+      "Bash(curl -s -o /dev/null -w \"GET /api/auth/get-session -> %{http_code}\\\\n\" http://localhost:50700/api/auth/get-session)",
+      "Bash(curl -s -o /dev/null -w \"GET /api/attachments/00000000-0000-0000-0000-000000000000/raw -> %{http_code} \\(404=route exists, no such id\\)\\\\n\" http://localhost:50700/api/attachments/00000000-0000-0000-0000-000000000000/raw)",
+      "Bash(curl -s -o /dev/null -w \"GET /api/documents \\(no auth\\) -> %{http_code} \\(401 expected\\)\\\\n\" http://localhost:50700/api/documents)",
+      "Bash(timeout 180 bun add --cwd frontend @tiptap/extension-table@^3.26.1)",
+      "Bash(timeout 180 bun add --cwd frontend @tiptap/extension-table@3.26.1)",
+      "Bash(curl -s -o /dev/null -w \"/register -> %{http_code}\\\\n\" http://localhost:50701/register)",
+      "Bash(curl -s -o /dev/null -w \"/docs/probe -> %{http_code}\\\\n\" http://localhost:50701/docs/00000000-0000-0000-0000-000000000000)",
+      "Bash(rm -f cj.txt img.png got_proxy.bin got_direct.bin)",
+      "Bash(curl -s -c cj.txt -b cj.txt -X POST http://localhost:50701/api/auth/sign-up/email -H 'Content-Type: application/json' -d '{\"name\":\"Img Test\",\"email\":\"__TRACKED_VAR__\",\"password\":\"password12345\"}' -w '\\\\nHTTP %{http_code}\\\\n')",
+      "Bash(curl -s -o /dev/null -w \"/search -> %{http_code}\\\\n\" \"http://localhost:50701/search?q=test\")",
+      "Bash(curl -s -o /dev/null -w \"/ \\(dash\\) -> %{http_code}\\\\n\" http://localhost:50701/)",
+      "Bash(curl -s -o /dev/null -w \"/ -> %{http_code}\\\\n\" http://localhost:50701/)",
+      "Bash(curl -s -o /dev/null -w \"/login -> %{http_code}\\\\n\" http://localhost:50701/login)",
+      "Bash(curl -s \"http://localhost:50701/api/share/PnWzf7hNeAZA_Aqdntkl3\")",
+      "Bash(python3 -c ' *)",
+      "Bash(git checkout *)",
+      "Bash(grep -n '>Import<\\\\|Import$\\\\|>All<\\\\|All$\\\\|<Upload' \"frontend/src/routes/\\(app\\)/+page.svelte\")",
+      "Bash(git --no-pager diff stash@{0} -- \"frontend/src/routes/\\(app\\)/docs/[id]/+page.svelte\")",
+      "Bash(git --no-pager diff \"stash@{0}\" -- \":\\(literal\\)frontend/src/routes/\\(app\\)/docs/[id]/+page.svelte\")",
+      "Bash(git --no-pager diff \"stash@{0}\" -- backend/src/api/routes/documents.ts)",
+      "Bash(git --no-pager diff \"stash@{0}\" -- frontend/package.json)",
+      "Bash(git --no-pager diff \"stash@{0}\" -- backend/src/lib/auth.ts)",
+      "Bash(git --no-pager diff \"stash@{0}\" -- backend/src/lib/config.ts)",
+      "Bash(git --no-pager diff \"stash@{0}\" -- frontend/src/routes/+layout.svelte)",
+      "Bash(git --no-pager diff \"stash@{0}\" -- frontend/src/routes/settings/+page.svelte)",
+      "Bash(grep -iE \"\\\\.env|secret|credential|\\\\.pem|\\\\.key$|id_rsa\")",
+      "Bash(git rm *)",
+      "Bash(awk '{print $NF}')",
+      "Bash(grep -ivE \"change-me|process\\\\.env|envSchema|z\\\\.string|placeholder|example|//|\\\\*|_SECRET=|_KEY=|_PASSWORD=|aipassword|minioadmin|description:|api-key-user|API_KEY=$|SECRET=change\")",
+      "Bash(grep -iE \"\\\\.env$|secret|\\\\.pem|\\\\.key$|credential\")",
+      "Bash(curl -s -o /dev/null -w \"/docs test -> %{http_code}\\\\n\" \"http://localhost:50701/docs/test\")",
+      "Bash(grep -n \"^## \\\\|^---$\" README.md)"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "playwright",
+    "stitch",
+    "sequential-thinking",
+    "firecrawl",
+    "rag",
+    "context7",
+    "mempalace",
+    "websearch",
+    "grep_app"
+  ]
+}

package/.dockerignore

@@ -0,0 +1,113 @@
+# ============================================
+# hiai-docs .dockerignore
+# Mirrors .gitignore with extra hardening for
+# image builds (no secrets, no VCS metadata,
+# no host volumes, no test artifacts).
+# ============================================
+
+# --- VCS ---
+.git
+.gitignore
+.gitattributes
+.github
+
+# --- Dependencies (re-installed inside image) ---
+node_modules
+**/node_modules
+# bun.lock is intentionally NOT ignored — required for `bun install --frozen-lockfile` reproducibility
+
+# --- Build outputs (regenerated inside image) ---
+dist
+build
+.svelte-kit
+.next
+.output
+**/.svelte-kit
+**/.next
+**/.output
+**/dist
+**/build
+packages/db/.drizzle
+
+# --- Paraglide generated (rebuilt in image) ---
+frontend/src/lib/paraglide
+
+# --- Secrets and local env (NEVER ship into image) ---
+.env
+.env.local
+.env.*.local
+**/.env
+**/.env.local
+!**/.env.example
+
+# --- Docker dev override (not needed in image) ---
+docker-compose.dev.yml
+
+# --- Local data volumes (host-only) ---
+minio_data
+ollama_data
+backup
+docker-data
+
+# --- Logs and runtime artifacts ---
+*.log
+logs
+**/*.log
+
+# --- Test artifacts ---
+coverage
+**/coverage
+**/*.test.ts
+**/*.test.tsx
+**/*.test.js
+**/*.spec.ts
+**/*.spec.tsx
+**/*.spec.js
+tests
+**/tests
+__tests__
+**/__tests__
+qa
+**/qa
+pytest.ini
+pytest-qa.ini
+
+# --- IDE / editor metadata ---
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# --- OpenCode workspace metadata ---
+.opencode
+.bob
+
+# --- Docs (only README.md ships into the image per Wave 0 spec) ---
+# Exclude all *.md, but make an exception for README.md (per W0.5 spec: "*.md (except README)")
+*.md
+!README.md
+docs
+
+# --- ML / dataset scratch ---
+mlops
+dataset
+models
+artifacts
+cache
+
+# --- Python envs (legacy) ---
+.venv
+**/.venv
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+
+# --- Backup / archive ---
+*.tar
+*.tar.gz
+*.tgz
+*.zip

package/.env.example

@@ -0,0 +1,68 @@
+# ============================================
+# hiai-docs Environment Configuration
+# Copy to .env and fill in your values
+# ============================================
+#
+# Wave 0 (W0.1) — Generate new random secrets before deployment.
+# Use: openssl rand -hex 32
+# IMPORTANT: Each domain MUST use its own secret. Do NOT reuse
+# BETTER_AUTH_SECRET for CSRF or MINIO_SECRET_KEY for webhooks.
+# ============================================
+
+# --- Database (shared ai-core infra) ---
+DB_USER=aiuser
+DB_PASSWORD=aipassword
+DB_NAME=hiai_docs
+DB_HOST=localhost
+DB_PORT=5433
+
+# --- Auth ---
+# Generate with: openssl rand -hex 32
+BETTER_AUTH_SECRET=change-me-to-random-32-chars
+BETTER_AUTH_URL=http://localhost:50700
+
+# --- CSRF ---
+# Dedicated signing key for CSRF tokens. Must differ from BETTER_AUTH_SECRET.
+# Generate with: openssl rand -hex 32
+CSRF_SECRET=change-me-to-random-32-chars
+
+# --- MinIO (shared ai-core infra) ---
+MINIO_ENDPOINT=localhost
+MINIO_PORT=9010
+MINIO_ACCESS_KEY=minioadmin
+# Generate with: openssl rand -hex 32
+MINIO_SECRET_KEY=change-me-to-random-32-chars
+MINIO_BUCKET=hiai-docs
+MINIO_USE_SSL=false
+
+# --- Webhooks ---
+# Dedicated HMAC key for inbound webhooks. Must differ from MINIO_SECRET_KEY.
+# Generate with: openssl rand -hex 32
+WEBHOOK_SECRET=change-me-to-random-32-chars
+
+# --- Redis (shared ai-core infra) ---
+REDIS_URL=redis://localhost:6380
+
+# --- Embeddings (shared ai-core Ollama) ---
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_MODEL=mxbai-embed-large  # 1024-dim
+EMBEDDING_OLLAMA_URL=http://localhost:11434
+EMBEDDING_FALLBACK_PROVIDER=openrouter
+EMBEDDING_FALLBACK_MODEL=openai/text-embedding-3-large
+
+# --- OpenRouter (fallback for embeddings) ---
+# Get a key from https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+
+# --- API Key Auth (for bots / programmatic access) ---
+# If set, requests with `Authorization: Bearer <key>` bypass Better Auth sessions.
+# Must be a unique random value (do NOT reuse BETTER_AUTH_SECRET).
+HIAI_DOCS_API_KEY=
+# The user ID assigned to API key-authenticated requests. Defaults to "api-key-user".
+OWNER_ID=api-key-user
+
+# --- App ---
+API_PORT=50700
+WEB_PORT=50701
+NODE_ENV=development
+LOG_LEVEL=info

package/.github/FUNDING.yml

@@ -0,0 +1,5 @@
+# Funding configuration for hiai-docs
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
+
+# These settings support the `hiai-dev` GitHub Sponsors account.
+github: [hiai-dev]

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,74 @@
+---
+name: Bug Report
+about: Report a bug in hiai-docs to help us improve
+title: "[BUG] "
+labels: ["bug", "needs-triage"]
+assignees: []
+---
+
+## Bug Description
+
+<!-- A clear, concise description of what the bug is. -->
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Click on '...'
+3. Run command '...'
+4. See error
+
+## Expected Behavior
+
+<!-- What you expected to happen. -->
+
+## Actual Behavior
+
+<!-- What actually happened. Include screenshots, error messages, or stack traces if applicable. -->
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| hiai-docs version | <!-- e.g. v0.1.0, commit SHA, or `main` --> |
+| Deployment | <!-- Docker / local dev / other --> |
+| Backend (Elysia) | <!-- version or commit --> |
+| Frontend (SvelteKit) | <!-- version or commit --> |
+| Database | <!-- PostgreSQL 18 + pgvector --> |
+| OS | <!-- e.g. Ubuntu 22.04, macOS 14 --> |
+| Browser | <!-- e.g. Chrome 120, Firefox 121 --> |
+| Bun version | <!-- `bun --version` output --> |
+
+## Configuration
+
+<!-- Relevant environment variables from `.env` (redact secrets). -->
+
+```bash
+EMBEDDING_PROVIDER=
+EMBEDDING_MODEL=
+DATABASE_URL=postgresql://***:***@***:**/hiai_docs
+```
+
+## Logs
+
+<!-- Paste relevant logs from `api`, `web`, or `docker compose logs`. Wrap in ```blocks```. Use [pastebin](https://pastebin.com) or similar for very long logs. -->
+
+```text
+[Paste logs here]
+```
+
+## Severity
+
+<!-- How badly does this affect you? -->
+
+- [ ] Critical — data loss, security issue, or complete outage
+- [ ] High — major feature broken
+- [ ] Medium — feature degraded but workaround exists
+- [ ] Low — minor cosmetic or edge case
+
+## Possible Cause
+
+<!-- Optional: your hypothesis on what might be causing the bug. -->
+
+## Additional Context
+
+<!-- Any other context, related issues, or PRs. -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,78 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement for hiai-docs
+title: "[FEATURE] "
+labels: ["enhancement", "needs-triage"]
+assignees: []
+---
+
+## Summary
+
+<!-- One-sentence description of the feature. -->
+
+## Problem / Use Case
+
+<!-- What problem does this solve? Who benefits? Describe the workflow or scenario. -->
+
+> As a [type of user], I want to [action] so that [outcome / value].
+
+## Proposed Solution
+
+<!-- Describe the desired behavior, API, or UI in detail. Mockups, ASCII diagrams, or links to references are welcome. -->
+
+### Example API / UI
+
+```http
+POST /api/documents/:id/duplicate
+Authorization: Bearer <token>
+```
+
+```svelte
+<Button on:click={duplicate}>Duplicate</Button>
+```
+
+### Database / Schema Changes (if any)
+
+<!-- Describe any new tables, columns, or migrations. -->
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider, and why is this one better? -->
+
+## Out of Scope
+
+<!-- What this feature should NOT do. Be explicit to keep scope tight. -->
+
+## Acceptance Criteria
+
+<!-- A clear checklist we can use to know the feature is done. -->
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Documentation updated (`docs/` and `README.md` if needed)
+- [ ] Tests added (unit + integration)
+- [ ] No breaking changes (or migration path documented)
+
+## Affected Areas
+
+<!-- Check all that apply. -->
+
+- [ ] Backend API (`backend/src/api/`)
+- [ ] Database schema (`packages/db/`)
+- [ ] Embedding pipeline (`backend/src/embedding/`)
+- [ ] Frontend pages (`frontend/src/routes/`)
+- [ ] Frontend components (`frontend/src/lib/`)
+- [ ] Docker / deployment
+- [ ] Documentation
+
+## Priority
+
+<!-- Your estimate of priority. Maintainers will adjust. -->
+
+- [ ] High — blocks current workflow for many users
+- [ ] Medium — valuable but not blocking
+- [ ] Low — nice-to-have
+
+## Additional Context
+
+<!-- Links, screenshots, references to similar features in Outline / Docmost / Notion, etc. -->

package/.github/dependabot.yml

@@ -0,0 +1,136 @@
+# Dependabot configuration for hiai-docs
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+
+# Update Bun lockfiles weekly (root + per-workspace)
+updates:
+  # ---------------------------------------------------------------------------
+  # Backend — Elysia REST API (Bun)
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "npm"
+    directory: "/backend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "backend"
+    groups:
+      production-dependencies:
+        dependency-type: "production"
+      development-dependencies:
+        dependency-type: "development"
+    commit-message:
+      prefix: "deps(backend)"
+      prefix-development: "deps(dev/backend)"
+      include: "scope"
+    # Elysia + Drizzle are sensitive to major bumps — only patch + minor
+    versioning-strategy: "increase"
+    ignore:
+      - dependency-name: "elysia"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "drizzle-orm"
+        update-types: ["version-update:semver-major"]
+
+  # ---------------------------------------------------------------------------
+  # Frontend — SvelteKit + Svelte 5 (Bun)
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "frontend"
+    groups:
+      production-dependencies:
+        dependency-type: "production"
+      development-dependencies:
+        dependency-type: "development"
+    commit-message:
+      prefix: "deps(frontend)"
+      prefix-development: "deps(dev/frontend)"
+      include: "scope"
+    versioning-strategy: "increase"
+    ignore:
+      - dependency-name: "svelte"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@sveltejs/kit"
+        update-types: ["version-update:semver-major"]
+
+  # ---------------------------------------------------------------------------
+  # Database package — Drizzle schema + migrations
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "npm"
+    directory: "/packages/db"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "db"
+    commit-message:
+      prefix: "deps(db)"
+      include: "scope"
+
+  # ---------------------------------------------------------------------------
+  # Docker base image updates (weekly digest bumps)
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "docker"
+    directory: "/backend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "docker"
+    commit-message:
+      prefix: "docker(backend)"
+
+  - package-ecosystem: "docker"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "docker"
+    commit-message:
+      prefix: "docker(frontend)"
+
+  # ---------------------------------------------------------------------------
+  # GitHub Actions — pin to digest for supply-chain hygiene
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"
+    groups:
+      actions:
+        patterns: ["*"]

package/.github/pull_request_template.md

@@ -0,0 +1,96 @@
+# Pull Request
+
+## Description
+
+<!-- Briefly describe what this PR does and why. Link the related issue with `Closes #123` or `Fixes #123`. -->
+
+Closes #
+
+## Type of Change
+
+<!-- Check all that apply. -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactor (no functional change)
+- [ ] Performance improvement
+- [ ] Test addition / improvement
+- [ ] CI / build / tooling change
+
+## Summary of Changes
+
+<!-- Bullet list of the meaningful changes. -->
+
+- 
+- 
+- 
+
+## Affected Areas
+
+<!-- Check all that apply. -->
+
+- [ ] Backend (`backend/`)
+- [ ] Frontend (`frontend/`)
+- [ ] Database schema (`packages/db/`)
+- [ ] Docker / deployment
+- [ ] Documentation
+- [ ] CI workflows
+
+## Database Changes
+
+<!-- If you modified Drizzle schema or migrations, describe them. -->
+
+- [ ] No schema changes
+- [ ] Schema change — `bun run db:generate` produced new migration(s)
+- [ ] Migration applied locally and tested
+
+## Testing
+
+<!-- Describe how you tested this change. Include commands you ran. -->
+
+### Local Verification
+
+```bash
+# Commands run locally
+bun install
+bun run lint
+bun run typecheck
+bun test
+```
+
+### Manual / E2E
+
+- [ ] Verified in `bun run dev:all` (backend + frontend)
+- [ ] Verified in `docker compose up -d`
+- [ ] Browser-tested with `agent-browser` (no Playwright)
+
+## Checklist
+
+<!-- Author self-review before requesting review. -->
+
+- [ ] Code follows the project's style and conventions (`AGENTS.md`)
+- [ ] Bun-native — no npm/yarn, no Node-only assumptions
+- [ ] ESM-only — no CommonJS
+- [ ] TypeScript strict — no `any` introduced, Zod validation on inputs
+- [ ] No hardcoded secrets, paths, or keys (all via `.env`)
+- [ ] `bun run lint` passes
+- [ ] `bun run typecheck` passes
+- [ ] `bun test` passes
+- [ ] New tests added for new functionality
+- [ ] Documentation updated (`docs/`, `README.md`, or inline JSDoc)
+- [ ] Self-reviewed the diff — no debug code, console.logs, or commented-out blocks
+- [ ] PR title follows Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`)
+
+## Screenshots / Recordings
+
+<!-- If UI changes, attach before/after screenshots or a short recording. -->
+
+## Breaking Changes & Migration
+
+<!-- If this is a breaking change, describe the migration path. -->
+
+## Additional Notes
+
+<!-- Anything reviewers should pay special attention to. -->