No description
  • JavaScript 81.9%
  • CSS 12.4%
  • Shell 5.4%
  • HTML 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
lea 6b99df73fa Link every occurrence of a selection on the page
A selected phrase is now linked everywhere it appears in the entry
summary and body, matching whole words regardless of casing while
leaving existing links untouched.

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
2026-11-12 15:41:41 +01:00
public Build Adaptedia self-writing encyclopedia 2026-11-09 22:05:50 +01:00
scripts Harden redirects, SSRF checks, auth boundaries and resource limits 2026-11-10 14:37:16 +01:00
server Link every occurrence of a selection on the page 2026-11-12 15:41:41 +01:00
src Link every occurrence of a selection on the page 2026-11-12 15:41:41 +01:00
tests Link every occurrence of a selection on the page 2026-11-12 15:41:41 +01:00
.env.example Add selection linking and model-assisted synonym matching 2026-11-12 11:21:02 +01:00
.gitignore Harden authentication, SSRF, job data and rate limits 2026-11-10 07:44:23 +01:00
index.html Replace external research with LLM knowledge recall 2026-11-10 08:10:37 +01:00
package-lock.json Add direct source discovery without a search API 2026-11-10 09:03:23 +01:00
package.json Add direct source discovery without a search API 2026-11-10 09:03:23 +01:00
README.md Add selection linking and model-assisted synonym matching 2026-11-12 11:21:02 +01:00
SECURITY.md Accept same-origin browser mutations behind proxies 2026-11-10 14:51:21 +01:00
vite.config.js Build Adaptedia self-writing encyclopedia 2026-11-09 22:05:50 +01:00

Adaptedia

A self-writing encyclopedia. Any path can become a permanent entry written from the configured model's knowledge and directly fetched pages. If the path does not name a subject, the editor declines it instead of inventing one.

Spaces in a requested path are normalized to hyphens, so /black holes becomes /black-holes. The page title is chosen by the editor independently of the path; a slug is only a hint.

Visit /anarchy on a fresh installation and the server will commission an entry, gather available sources, write it, and store it. The next visit serves the stored page. Visit /usdhfsh and the editor will say that it cannot see a subject there; that refusal is stored too.

Adaptedia uses no search API. The model generates the search query; the app searches through DuckDuckGo's HTML interface or an optional self-hosted SearXNG instance, then fetches the result pages over HTTPS. The only outbound API is the configured LLM provider.

What happens on a missing path

  1. The configured model classifies the path as a subject or noise, chooses the canonical page title independently of the slug, and decides whether the subject should be an article or a list.
  2. The editor generates two or three search queries. The app searches its own published entries, then searches through DuckDuckGo HTML or a self-hosted SearXNG instance, fetches every unique result it can, and keeps all usable pages.
  3. A second model call produces a knowledge brief from those pages when available, otherwise from internal knowledge, with confidence and uncertainties.
  4. If there is not enough material, nothing is written. The path fails with an explanation and no page is stored.
  5. The model writes a Markdown entry using only the knowledge brief and fetched sources.
  6. A fact-check pass audits the summary and body against the brief and fetched sources, removes unsupported or overconfident claims, and either approves the entry, marks it as limited, or rejects it. A rejected draft is never published.
  7. A supported entry is written atomically to data/pages/ and served at the same path from then on. Limited entries carry a visible evidence note; model-knowledge entries carry a basis note.

Before writing, the editor checks the published entries for the same subject. Exact names and learned aliases resolve instantly; when those miss, one small model call compares the request against a shortlist of entries, so an abbreviation or expansion still finds its entry. A hit is stored as an alias, so it resolves without the model afterwards. When a requested path is another name for an existing entry, no second entry is written: visiting it opens the existing page and replaces the address bar with that page's path.

Readers can select text inside an entry and choose Link from the context menu. The linking editor chooses the existing entry that best explains the phrase, or names a new subject and starts its generation. It reports the exact words from the stored Markdown that should become the link, and the server wraps only those words; if the phrase cannot be located, nothing is changed. All links stay internal.

Generation runs in the background, so the page can report progress while it works. Only one job runs per path. Four jobs may run at once. A job stops automatically after six minutes instead of hanging.

Requirements

  • Node.js 20.18.1 or newer
  • An API key for DeepSeek, CommandCode, or Inception

Run locally

npm install
npm run build
npm start

Open http://localhost:3000. Settings is protected by HTTP Basic authentication. If ADAPTEDIA_ADMIN_PASSWORD is not set, the server generates one at data/admin-password on first start:

cat data/admin-password

The username is admin. Open /settings, use the browser login prompt, then choose a provider and model and add its API key. The key is stored server-side in data/settings.json with mode 0600; it is never returned to the browser.

For development with Vite middleware and HMR:

npm run dev

The development server uses the same port and API.

Providers

Provider API root Environment fallback
DeepSeek https://api.deepseek.com/v1 DEEPSEEK_API_KEY
CommandCode https://api.commandcode.ai/provider/v1 COMMAND_CODE_API_KEY
Inception https://api.inceptionlabs.ai/v1 INCEPTION_API_KEY

All three use the OpenAI-compatible /chat/completions and /models routes. Model ids can be typed directly or loaded from the provider in Settings.

For a gateway or a local mock, override a provider root:

ADAPTEDIA_DEEPSEEK_BASE_URL=http://127.0.0.1:8080/v1
ADAPTEDIA_COMMANDCODE_BASE_URL=http://127.0.0.1:8080/v1
ADAPTEDIA_INCEPTION_BASE_URL=http://127.0.0.1:8080/v1

Configuration

Copy .env.example if you want environment-based configuration, and keep it private (chmod 600 .env). The app reads:

Variable Default Purpose
PORT 3000 HTTP port
HOST 0.0.0.0 in production, 127.0.0.1 in dev Listen address; the example file uses localhost
ADAPTEDIA_DATA_DIR ./data Settings, admin password and stored pages
ADAPTEDIA_ADMIN_USER admin Settings login username
ADAPTEDIA_ADMIN_PASSWORD generated file Settings login password
ADAPTEDIA_GENERATION_LIMIT 12 New pages allowed per client IP per hour
ADAPTEDIA_SYNONYM_LIMIT 60 Model-assisted name lookups per client IP per hour
ADAPTEDIA_LINK_LIMIT 60 Links added through the selection menu per client IP per hour
ADAPTEDIA_WEB_SEARCH 1 Use API-less web search; set to 0 for internal knowledge only
ADAPTEDIA_SEARCH_URL none Optional self-hosted SearXNG base URL; can also be set in Settings
ADAPTEDIA_TRUST_PROXY 0 Set to 1 only behind a trusted reverse proxy
ADAPTEDIA_DEEPSEEK_BASE_URL DeepSeek API Endpoint override
ADAPTEDIA_COMMANDCODE_BASE_URL CommandCode API Endpoint override
ADAPTEDIA_INCEPTION_BASE_URL Inception API Endpoint override
DEEPSEEK_API_KEY none Fallback key, overridden by a saved key
COMMAND_CODE_API_KEY none Fallback key, overridden by a saved key
INCEPTION_API_KEY none Fallback key, overridden by a saved key

Data

data/
  settings.json        provider, model, saved keys (0600)
  admin-password       generated settings password (0600), when no env password
  pages/<hash>.json    one permanent entry per path, published or declined

Pages include the title, summary, Markdown body, provider, model, timestamps, word count, fact-check result and evidence basis. Back up data/ to keep the encyclopedia and the admin password. Administrators can delete an entry with the Delete page control in the page's left rail. Enter the admin password in the confirmation dialog, or leave it blank if the browser is already signed in. The path will be generated again on its next visit. Deleting an entry file directly has the same effect.

Accuracy and knowledge

Adaptedia uses no third-party search API. The model generates two or three queries. The app first looks for relevant published Adaptedia entries, then searches through DuckDuckGo's HTML interface or an optional self-hosted SearXNG instance and fetches every unique result page. Local entries are marked as internal context, not independent verification. If none of that yields material, it falls back to internal model knowledge.

  • Slugs are resolved as named entities where possible. A plausible hyphenated name is passed to knowledge recall even if the commissioning editor does not recognize it.
  • Relevant Adaptedia entries are included as internal context; fetched pages are treated as evidence. The model builds a knowledge brief from both.
  • If no source is found and the model does not know enough, nothing is written.
  • Writing is restricted to the knowledge brief and fetched sources.
  • A separate fact-check pass checks the draft against that material, removes unsupported claims, and can reject the entire entry.
  • Pages with fetched sources show citations and a source list. Pages without them show a basis note saying that no external sources were fetched.
  • Lower-confidence entries get an evidence note and a Limited fact-check status.
  • Empty, malformed, rate-limited and transient provider responses are retried automatically before the job fails.
  • When the editor decides a subject is a list rather than an article, it generates the actual list from model knowledge, without source fetching or citations. It must not become an article about another list.
  • A rejected draft is not saved, so reloading the path retries generation rather than serving the rejected text.

Search quality depends on the query and the search backend. DuckDuckGo can rate-limit HTML requests, so a self-hosted SearXNG instance is the reliable option:

ADAPTEDIA_SEARCH_URL=http://127.0.0.1:8080

SearXNG is queried without an API key; JSON is used when enabled, otherwise its HTML results are parsed. Admins can set or change the base URL in Settings; the saved value overrides the environment fallback. The search URL is server-side and may point at a private address.

Search results can be incomplete or wrong, and the model can be outdated or mistaken; the fact-checker is another model call. Treat every entry as generated material and verify consequential claims independently.

Tests

npx playwright install chromium
npm run test:e2e

tests/e2e.sh does not delete itself. It packs the application, installs that package into a temporary directory, runs a mock OpenAI-compatible provider, and exercises the real server: admin authentication, unauthorized settings access, generation rate limiting, security headers, settings, model discovery, generation, knowledge recall, named-entity slug resolution, fact-checking, limited-evidence notes, rejected drafts that are never published, repeat visits, refusals, reserved paths, the browser UI, mobile overflow, and persistence across a restart. It removes the temporary installation on exit and leaves screenshots in test-artifacts/.

If Chromium is installed in a non-standard place, set CHROMIUM_PATH. To run only the API checks, set SKIP_UI=1.

Proxmox VE

On the Proxmox host, run:

bash -c "$(curl -fsSL https://git.new-eve.org/redforged/adaptedia/raw/branch/main/scripts/proxmox.sh)"

It asks for confirmation, then creates an unprivileged Debian 12 container at the next free ID with 2 GB RAM, 1 core, and 16 GB disk, installs Node.js 22, clones redforged/adaptedia, builds it, and starts it on port 3000. It prints the generated admin username and password at the end. Put a TLS reverse proxy in front before exposing it publicly.

For a container that predates admin authentication, update it and then read the generated password:

pct exec <CTID> -- update
pct exec <CTID> -- cat /opt/adaptedia/data/admin-password

The container gets an update command (also adaptedia-update). From the Proxmox host:

pct exec <CTID> -- update

Older installs could leave a generated change in package-lock.json that blocks git pull. If an update reports that, discard the generated lockfile once as the service user, then run the update again:

pct exec <CTID> -- runuser -u adaptedia -- env HOME=/opt/adaptedia git -C /opt/adaptedia/app checkout -- package-lock.json
pct exec <CTID> -- update

The current installer and update command use npm prune --omit=dev --package-lock=false, so they no longer create that change.

For an existing container made before the update command existed, install it once:

pct exec <CTID> -- bash -c 'curl -fsSL https://git.new-eve.org/redforged/adaptedia/raw/branch/main/scripts/update.sh -o /usr/local/bin/adaptedia-update && chmod 755 /usr/local/bin/adaptedia-update && ln -sf /usr/local/bin/adaptedia-update /usr/local/bin/update'

The container console logs in as root without a password. Only the container's TTY1 is affected; access to it is still protected by the Proxmox web interface. Existing containers can enable it with:

pct exec <CTID> -- bash -c 'curl -fsSL https://git.new-eve.org/redforged/adaptedia/raw/branch/main/scripts/console-autologin.sh | bash'

Security and scope

The current review and residual risks are in SECURITY.md.

  • /settings, the settings API and model discovery require HTTP Basic admin authentication. Failed logins are rate limited.
  • New-page generation is public by design and limited to 12 requests per client IP per hour. Raise or lower it with ADAPTEDIA_GENERATION_LIMIT. Put a reverse proxy with authentication in front if the deployment is open to the internet and generation cost matters.
  • If Adaptedia runs behind a trusted TLS reverse proxy, set ADAPTEDIA_TRUST_PROXY=1 so client IPs and HTTPS detection work. Do not set it when clients can reach the app directly.
  • Settings and API keys use files with mode 0600, but keys are stored in plaintext. Protect the host and backups accordingly.
  • Fetched search results require HTTPS and block private, loopback, link-local, multicast, metadata and mapped addresses. The connection is pinned to the checked public address. There is no third-party search API.
  • The only external API is the configured LLM provider.
  • The application is intentionally single-process and file-backed. It has no database, editor roles, page editing, or persistent queue.
  • A provider failure leaves no page; retry the path. A refusal or a published page is permanent until its JSON file is removed.
  • HTTP Basic credentials are only as safe as the transport. Use a TLS reverse proxy before exposing the settings interface beyond a trusted LAN.
  • The Proxmox installer enables passwordless root autologin on TTY1. Anyone who can open the container console through the Proxmox UI has root in the container. Secure Proxmox accounts with strong passwords and 2FA, or remove the TTY1 autologin drop-ins.