knowledge-workspace

Knowledge workspace

Save sources, search your knowledge, and draft with the original context.

The video shows real public product captures and the TypeScript behind the agent’s source-reading tool. A live agent conversation requires sign-in.

Tags: AI · AIAgent · KnowledgeWorkspace · TypeScript · NextJS · BuildInPublic · Developer

A TypeScript Next.js App Router app with the compact Cursor-style library, threads, articles, keyboard shortcuts, and bottom composer. It includes Drizzle schema/migrations, Neon managed auth integration, and a Vercel Eve agent.

Run

1npm install
2npm run setup:env
3npm run dev

Open http://127.0.0.1:5173 for the landing page; the workspace is at /app. The landing follows the measured Cursor marketing layout and includes an actual live workspace, provenance-backed source screenshots, isolated editable notes, responsive navigation, source tabs, and FAQs. These examples never seed the library. Local library search, editing, uploads, templates, and exports work without account credentials. npm run build builds Eve and Next.js; npm start runs both through the Next.js integration.

New libraries and chats start empty. Starter cards, canned chat messages, the placeholder account name, and example automation routines have been removed. Previously seeded browser items are filtered by their known IDs; uploaded and newly created resources remain. A local cursor-knowledge-workspace-v1:starter-archive preserves the old browser state for recovery. No resources are seeded into Neon.

Activation status

The new knowledge_workspace database is configured in the selected Chrome account's Vercel: ahmed's projects organization. Because this organization disables new projects, setup created a schema-only knowledge-workspace branch inside neon-blue-xylophone (bold-king-26717419). The branch ID is br-red-unit-a21710wa; it contains no copied parent data. Setup does not modify the original main branch's data or compute.

The Drizzle migration is applied: resources, workspaces, and agent_sessions, including owner indexes and the full-text search index. Neon Auth is enabled for knowledge_workspace, with http://127.0.0.1:5173 trusted for local development. The branch compute is fixed at 0.25 CU, with five-minute idle suspension. No plan upgrade was made; account usage allowances still apply.

Pooled/direct database connections and the auth endpoint are saved in the private .env.local with certificate verification enabled. Cookie and agent secrets are retained. The CLI profile still belongs to a different account; CLI sign-in is unnecessary to run the configured app. Sign into the selected account before future CLI infrastructure changes.

Set these server variables:

The local app has been restarted with these variables. Create your app account or sign in at /auth/sign-in. The workspace requires a server-verified login. Existing Neon resources load on sign-in and later changes save automatically. Browser caches are scoped to each account. Add the production origin to managed auth's trusted domains when deploying. The archive excludes credentials, so another checkout requires its own private environment configuration.

The library has direct Sign in actions in its header, sidebar, and browser-library notice. Account errors are shown explicitly. The requested app user was created through Neon Auth's console. Use Set or reset password on the sign-in page to request a secure email link, then choose your password yourself. The app includes /auth/reset-password for that link. Password setup and authenticated sign-in still require the account holder; no password was generated or stored by setup.

Free models and Eve

Use either an OpenRouter API key in OPENROUTER_API_KEY or a running local Ollama server with OLLAMA_MODEL and OLLAMA_BASE_URL. The supplied OpenRouter key is configured privately in this checkout. Live zero-price inference and tool calls passed for Cohere North Mini Code and the OpenRouter free router. Qwen 3.8 27B passed schema-validated source summarization and real screenshot reading. No Ollama server was found. The key is excluded from source and archives.

The model menu reads the live catalog and lists models reporting zero pricing. The resolver checks prompt, completion, and every supplied pricing field, rejects paid models, and verifies tool/vision capability. Hosted requests also include a zero max_price cap and disable provider fallback, following OpenRouter's routing API. Provider availability and free rate limits still apply. Hosting and database allowances are separate from model pricing.

AGENT_MODEL is the server default. EXTRACTOR_MODEL, WRITER_MODEL, and VISION_MODEL select verified free models for source analysis, post-tool agent responses, and image reading. The current agent/writer is cohere/north-mini-code:free; extractor/vision is qwen/qwen3.8-27b:free. Import and image roles require structured-output support and return schema-validated data. An explicitly selected composer model takes precedence for agent turns; imports use the extractor role independently. Settings displays the verified roles. Availability is checked against the live catalog and may change. Ollama IDs use ollama:MODEL_NAME.

The agent can search and filter the signed-in user's knowledge, read attached resources and complete uploaded files in chunks, fetch up to three public URLs concurrently, import linked sources as separate related resources, summarize and tag them, capture real screenshots, describe uploaded images, and write code or editorial drafts. Source/vision analysis has a three-call concurrency limit per server process. Default shell and filesystem tools are disabled; code drafts are not executed. Local Eve workflow state is under .eve/.workflow-data; preserve it when self-hosting.

Browser agent requests pass through authenticated Next.js handlers. Sessions are mapped to their owner in Neon; the Eve channel independently verifies short-lived signed tokens and session ownership. All database reads/writes include the user's owner ID.

Sources, files, and media

Use Add a link or note, or Upload a file. Signed-in imports read real source text and metadata, then attempt analysis. Without model credentials, the source is still saved with an explicit warning and remains Needs review. Without sign-in, URLs are saved as unfetched links and provided text stays in browser storage. No completed fetch or model result is simulated.

Uploads support images and common text/code formats up to 2 MB, including Markdown, JSON, CSV, HTML, TypeScript, Python, C/C++, Rust, Go, CSS, SQL, and configuration files. The agent only reads files you upload; it cannot browse arbitrary folders on your computer. PDF and Word parsing are not implemented. Page fetching is limited to 1.5 MB; readable page text is capped at 60,000 characters, with at most 22,000 sent to the source analysis model. Full uploaded file text is stored and searchable; model reading uses bounded chunks.

Public fetching validates and pins DNS addresses, checks each redirect, blocks local/private networks, caps response size, and times out. Included links are followed only when selected, up to three per import. Model-generated tags and articles remain Needs review.

Real page screenshots require:

1npx playwright install chromium

Set ENABLE_SCREENSHOTS=true and restart. Chromium is installed and capture is enabled in this workspace's private local environment. Screenshot capture is restricted to the source hostname, with service workers, downloads, and WebSockets disabled; cross-domain assets may be missing. This is a real capture, not a generated cover. Live capture through the authenticated agent still needs end-to-end verification. The free vision adapter has been tested against the real BoardUI screenshot.

Curated covers are original source screenshots and the original thumbnail from Nero's BoardUI post. Provenance is in public/previews/sources.json. The X video opens on its original source because the CDN rejected localhost playback. Notes without media have no cover. Remote access blocks are reported; pasted text or original uploaded screenshots can supply the evidence.

UI and verification

Light mode is the default. Use the header theme toggle or Settings → Appearance to choose Light or Dark; the preference persists across reloads and tabs, including the sign-in page. Source images retain their original colors.

Custom styles use warm neutral surfaces and a muted green action color. Controls have focus feedback, short press feedback, and compact menu transitions; the sidebar keeps its 280px/44px scale. System reduced-motion preferences disable movement and smooth scrolling.

Cmd/Ctrl+K searches resources and threads. Cmd/Ctrl+Alt+B toggles the sidebar. Cards open full articles with source metadata, tags, relationships, summary files, editable notes, and editorial drafts. Tweet, article outline, image brief, and tweet JSON templates are labeled drafts; local templates are distinct from model output.

1npm run typecheck
2npm test
3npm run build
4npm run db:generate

See VALIDATION.md for tested behavior and remaining live-service checks. Keep .env.local, .neon, workflow state, and build outputs out of source archives.

Local HTTPS and Safari sign-in

Neon Auth uses Secure session cookies. Safari cannot keep these on a plain HTTP preview. Use npm run dev:https, then open https://localhost:5174. The launcher redirects old http://127.0.0.1:5173 bookmarks to HTTPS. Stop any existing development server before starting this command.

Certificates are machine-local and excluded from source and archives. On a fresh machine, generate a localhost certificate and trust it with the machine owner's approval:

1mkdir -p certificates
2openssl req -x509 -newkey rsa:2048 -sha256 -days 90 -nodes -keyout certificates/localhost-key.pem -out certificates/localhost.pem -subj '/CN=localhost' -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:::1' -addext 'basicConstraints=critical,CA:FALSE'
3chmod 600 certificates/localhost-key.pem
4# macOS: explicitly trust only this certificate for localhost SSL.
5security add-trusted-cert -r trustRoot -p ssl -s localhost -k "$HOME/Library/Keychains/login.keychain-db" certificates/localhost.pem
6npm run dev:https

The launcher passes the certificate to Node for its own HTTPS calls, keeps the server bound to loopback, and sets the internal agent origin to the HTTPS app. Production should use the hosting provider's normal HTTPS certificate. Never commit the private key.

Account setup now checks the actual session before redirecting. Creating an account without a retained session keeps the user on the sign-in page with an explanation. Account settings displays the authenticated user's email and verification status; name changes are saved through Neon Auth. The public landing page does not embed the private workspace. Signed-out requests to /app redirect to /auth/sign-in, and sign-out returns there immediately.

Agent chat and source workflow

The authenticated Eve proxy preserves stream version, format, session ID, and tail-index headers. The local HTTPS launcher explicitly passes the local certificate as Next.js's HTTPS CA so server-to-server agent requests retain certificate verification.

Chat shows running/completed tool actions, persistent failures, retry and stop controls, and formatted Markdown. Model choice is stored per account. Responses, sessions, sources and drafts save to Neon. Source analysis uses the verified free extractor model; linked sources can run concurrently under the configured limit.

Cloud refresh uses a pure resource merge. Autosave pauses during agent work, snapshots only changed resources before scheduling a request, and prevents old acknowledgements from replacing a newer cloud baseline. This preserves agent-attached screenshots while retaining unsaved local edits.

Database upserts also retain the newest source screenshot when an older tab submits resource changes. Local edits merge with fresh cloud media instead of deleting it.

Thread index and split source chat

Apply drizzle/0001_thread_titles.sql to an existing database before starting this version. The migration copies previous workspace threads into separate indexed rows without removing originals. Workspace loading returns at most 100 title/metadata records; /api/threads paginates titles and returns full messages only for a requested thread ID. All queries are scoped to the authenticated owner. Title-only sync updates preserve unloaded messages.

The AI search command supports indexed thread-title search and opening an agent request. Source details provide a resizable source chat with authenticated source context, editable notes, and explicit delete confirmation. Source removal retains the database row. Thread deletion moves the thread to Trash and can be restored.

Agent UI uses assistant-ui's ExternalStoreRuntime adapter over the existing Eve stream. Source chat uses message and composer primitives; the main composer shares the adapter. See design/unslop/analysis.md and design/unslop/skill.md for the reference-specific UI review and its limitations.

Production

The workspace is deployed in the Qentrah Vercel team at https://base.qentrah.com/app. The GitHub repository is connected for deployments from main. Production credentials are stored as sensitive Vercel environment variables. Neon Auth trusts https://base.qentrah.com; Cloudflare DNS points only the base subdomain at Vercel. vercel.json runs the Eve and Next.js production build. Local credentials, certificates, and work artifacts are excluded from uploads through .vercelignore.

License

The project source code is available under the MIT License. Third-party dependencies and original source images, screenshots, and thumbnails retain their respective licenses and copyrights.