knol.space

Invite-only multi-user knowledge spaces with Google sign-in, Markdown sync, graph navigation, media ingestion, and inline handwriting blocks.

The hosted source of truth is Postgres and S3. Markdown remains the portable import/export/sync format for agents, local editors, Obsidian-style workflows, and backups.

Stack

• Next.js + TypeScript app router
• Prisma + PostgreSQL 16 with pgvector
• NextAuth Google OAuth with invite-gated account creation
• S3 for media, ink renderings, attachments, and exports
• SQS plus a worker service for media, OCR, embeddings, and concept extraction
• ECS Fargate web and worker services behind an ALB
• Route 53 and ACM for knol.space and www.knol.space

Local Development

cp .env.example .env
docker compose up postgres localstack
npm install
npm run db:push
npm run dev

Open http://localhost:4173.

Set PLATFORM_ADMIN_EMAILS in .env to bootstrap the first admin user. Google OAuth redirect URI for production is:

https://knol.space/api/auth/callback/google

CLI

Install from npm:

npm install -g knol.space
knol auth
knol spaces
knol use SPACE_ID_OR_SLUG

During knol auth, the CLI opens the browser, uses your Google session, and then prompts for a default space. If your account has no spaces yet, it can create the first one during onboarding.

Then use it without passing tokens or space IDs each time:

knol whoami
knol create-space "Research"
knol add "Document Title" --tags topic
knol add "https://youtube.com/watch?v=..."
knol add robotics/to-read "https://example.com/article"
knol robotics/to-read "https://example.com/article"
knol search "query"
knol sync push --dir content
knol sync pull --dir content
knol ingest robotics/videos "https://youtube.com/watch?v=..."

knol auth opens knol.space in the browser, uses your Google session, and stores a local user token in ~/.knol/config.json. Use KNOL_API_URL=http://localhost:4173 only when targeting the local dev server.

Agent Skills

Install Codex skills and Claude slash commands:

knol install-skills

Then use:

/knol-add <url or description>
/knol-search <query>

The installed skills call the same knol CLI and use the credentials from knol auth.

Web Routes

• /login
• /spaces
• /spaces/:spaceId
• /spaces/:spaceId/docs/:docId
• /spaces/:spaceId/graph
• /spaces/:spaceId/media
• /admin

API Routes

• POST /api/invites
• GET/POST /api/spaces
• GET/POST /api/documents
• GET/PATCH/DELETE /api/documents/:id
• POST /api/documents/:id/blocks
• POST /api/media/upload-url
• POST /api/media/ingest-url
• GET /api/jobs/:id
• GET /api/search
• GET /api/graph
• GET /api/backlinks
• POST /api/sync/import
• GET /api/sync/export
• POST /api/tokens

AWS Bootstrap

Use root credentials only once to create a non-root deploy user:

ROOT_CSV=~/Downloads/root.csv npm run bootstrap:aws-root

The script creates a temporary local AWS profile named root-bootstrap, creates the knol-deployer IAM user/profile, writes the deploy access key to knol-deployer.csv, and removes the temporary root profile credentials.

Deploy with the non-root profile:

export AWS_PROFILE=knol-deployer
export AWS_REGION=us-east-1
npm run deploy:aws

The CloudFormation stack outputs Route 53 nameservers. Update Namecheap manually to those nameservers before the ACM certificate can validate and the knol.space records can serve traffic.

Runtime secrets live in Secrets Manager at /knol-space/runtime; replace the placeholder Google, OpenAI, Gemini, and session secret values after stack creation.

Tests

npm test

Current tests cover Markdown round trips, wikilinks, block references, invite role ordering, and API token scope rules.

Security Notes

• Do not commit .env, API tokens, OAuth secrets, AWS keys, media credentials, or robot credentials.
• API tokens are space-scoped and should use the narrowest scope needed.
• Users may ingest only media they own or are authorized to process.
• Root AWS access keys should be deleted or deactivated after the deploy identity is created.