docs: align config and github workflow

.claude/skills/commit/SKILL.md

@@ -26,8 +26,8 @@ standard. The format is enforced by `gitlint` in the `commit-msg` hook.
    ```
 
 5. Never use `--no-verify`. If pre-commit hooks fail, fix the cause and re-commit.
-6. Do not commit secrets, generated artifacts, or work-in-progress to a
-   protected branch (`main` / `dev` / `master`).
+6. Do not commit secrets, generated artifacts, or work-in-progress directly to
+   the protected `main` branch.
 
 ## Types
 

.claude/skills/new-branch/SKILL.md

@@ -1,43 +1,44 @@
 ---
 name: new-branch
-description: Create a branch following the project's GitFlow Lite model
+description: Create a GitHub branch from main with the project naming convention
 ---
 
 # /new-branch
 
-Cut a new branch under the GitFlow Lite model.
+Cut a new branch for the GitHub repository.
 
 ## Branch model
 
 ```
-master  = released / stable (tagged on release; protected)
-dev     = integration branch (protected)
-feat/*  = cut from dev  → PR → merge into dev
-fix/*   = cut from dev  → PR → merge into dev
-hotfix/* = cut from master → merge into master AND synced into dev (double merge)
-release  = dev → master + tag on master (no separate release branch)
+main       = default and protected branch
+feat/*     = feature work
+fix/*      = bug fixes
+docs/*     = documentation-only changes
+ci/*       = CI, build, and developer-experience changes
+chore/*    = repository maintenance
+refactor/* = behavior-preserving code structure changes
 ```
 
 ## Steps
 
-1. Ask (or infer) the change type: `feat`, `fix`, or `hotfix`.
-2. Pick the parent:
-   - `feat/*`, `fix/*` → branch from **`dev`**.
-   - `hotfix/*` → branch from **`master`**.
-3. Update the parent first:
+1. Ask (or infer) the change type: `feat`, `fix`, `docs`, `ci`, `chore`, or
+   `refactor`.
+2. Update `main` first:
    ```bash
-   git checkout <parent>
+   git checkout main
    git pull --ff-only
    ```
-4. Create the branch with a kebab-case slug:
+3. Create the branch with a kebab-case slug:
    ```bash
-   git checkout -b feat/<short-slug>
+   git checkout -b <type>/<short-slug>
    ```
-5. For a `hotfix`, remember it must later merge into **both** `master` and `dev`.
+4. Keep the branch scoped to one purpose and open a pull request back to
+   `main`.
 
 ## Naming
 
-- `feat/add-agentic-rerank`, `fix/empty-profile-crash`, `hotfix/lancedb-conn-leak`.
+- `feat/add-agentic-rerank`, `fix/empty-profile-crash`,
+  `docs/quickstart-config`, `ci/check-github-docs`.
 - Lowercase, hyphen-separated, no spaces, concise.
 
-Never commit directly to `master` or `dev` — always via a branch + PR.
+Never commit directly to `main` — always use a branch and pull request.

.claude/skills/pr/SKILL.md

@@ -10,8 +10,9 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 ## Steps
 
 1. Confirm the branch and target:
-   - `feat/*`, `fix/*` → base **`dev`**.
-   - `hotfix/*` → base **`master`** (then a follow-up PR/sync into `dev`).
+   - Base branch is **`main`**.
+   - Head branch should be a scoped branch such as `feat/*`, `fix/*`,
+     `docs/*`, `ci/*`, `chore/*`, or `refactor/*`.
 2. Ensure local checks pass first:
    ```bash
    make ci
@@ -24,7 +25,7 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 4. Create the PR, filling the template
    ([.github/PULL_REQUEST_TEMPLATE.md](../../../.github/PULL_REQUEST_TEMPLATE.md)):
    ```bash
-   gh pr create --base dev --fill-first
+   gh pr create --base main --fill-first
    ```
    Then edit the body to complete each section:
    - **Summary** — what changed and why.
@@ -38,4 +39,5 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 
 - Keep the PR scoped to one area. Split unrelated changes.
 - If `make ci` was not fully run, say so in Verification rather than implying it passed.
-- A `hotfix` is not done until it has landed on **both** `master` and `dev`.
+- Never retarget a community PR away from `main` unless a maintainer explicitly
+  asks for it.

.github/workflows/docs.yml

@@ -7,15 +7,23 @@ on:
       - ".github/ISSUE_TEMPLATE/**"
       - ".github/PULL_REQUEST_TEMPLATE.md"
       - ".github/workflows/docs.yml"
+      - ".claude/skills/**/*.md"
+      - "CLAUDE.md"
+      - "CONTRIBUTING.md"
       - "scripts/check_docs.py"
+      - "scripts/check_github_contributor_docs.py"
   push:
     branches: [main]
     paths:
       - "**/*.md"
       - ".github/ISSUE_TEMPLATE/**"
       - ".github/PULL_REQUEST_TEMPLATE.md"
       - ".github/workflows/docs.yml"
+      - ".claude/skills/**/*.md"
+      - "CLAUDE.md"
+      - "CONTRIBUTING.md"
       - "scripts/check_docs.py"
+      - "scripts/check_github_contributor_docs.py"
 
 permissions:
   contents: read

CITATION.md

@@ -32,9 +32,9 @@ BibTeX citation information will be added here once the paper is published.
 To cite the software itself:
 
 ```
-EverOS: md-first memory extraction framework for AI agents
-Version: 0.1.0
-URL: https://github.com/EverMind-AI/everos
+EverOS: local-first memory runtime for AI agents
+Version: 1.1.0
+URL: https://github.com/EverMind-AI/EverOS
 License: Apache 2.0
 ```
 

CLAUDE.md

@@ -47,9 +47,19 @@ Contributor engineering reference — build, test, CI gates, branch & commit con
 
 ## Branch strategy
 
-`master` = released stable (hidden); `dev` = integration; `feat/* fix/*` → dev; `hotfix/*` → master + dev (sync).
+`main` is the default and protected branch. Create scoped branches from
+`main` (`feat/*`, `fix/*`, `docs/*`, `ci/*`, `chore/*`, `refactor/*`) and open
+pull requests back to `main` after the required checks pass.
 
-See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md) for the full GitFlow Lite rationale.
+See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md)
+for the full branch workflow.
+
+## GitHub sync guard
+
+When refreshing this repository from an internal source archive, preserve
+GitHub-only contributor and automation files. Do not overwrite `CLAUDE.md`,
+`.claude/skills/*`, `CONTRIBUTING.md`, or `.github/*` workflow/template files
+without checking [docs/github-sync.md](docs/github-sync.md).
 
 ## Storage three-piece set
 

CONTRIBUTING.md

@@ -91,7 +91,7 @@ internally.
 git clone https://github.com/EverMind-AI/EverOS.git
 cd EverOS
 make install             # deps + pre-commit hooks (one-stop dev setup)
-everos init              # write ./.env, then fill in the API key slots
+everos init              # write ~/.everos/everos.toml + ome.toml
 make ci                  # verify: lint + unit + integration + package
 ```
 
@@ -153,7 +153,7 @@ Full conventions: [.claude/rules/testing.md](.claude/rules/testing.md).
 
 - `/new-branch` — create branch with proper naming
 - `/commit` — generate a Conventional Commits message
-- `/pr` — internal merge request with correct target branch
+- `/pr` — open a GitHub pull request with the correct target branch
 
 ---
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-deps lint docs-check check-commits check-pr-title check-assets check-deprecated-names check-cjk check-datetime openapi check-openapi format test integration package cov ci clean
+.PHONY: help install install-deps lint docs-check check-commits check-pr-title check-assets check-deprecated-names check-github-docs check-cjk check-datetime openapi check-openapi format test integration package cov ci clean
 
 help:
 	@echo "Targets:"
@@ -10,6 +10,7 @@ help:
 	@echo "  check-pr-title Validate PR title uses Conventional Commit format"
 	@echo "  check-assets  Block committed images, videos, and asset/media directories"
 	@echo "  check-deprecated-names Block deprecated product names"
+	@echo "  check-github-docs Block legacy/internal branch-model residue in contributor docs"
 	@echo "  check-cjk     Scan for CJK outside the language-policy allowlist (advisory)"
 	@echo "  check-datetime Scan for code that bypasses component/utils/datetime (HARD gate, run via lint)"
 	@echo "  openapi       Regenerate docs/openapi.json from the FastAPI app"
@@ -39,11 +40,13 @@ lint:
 	uv run lint-imports
 	uv run python scripts/check_repo_assets.py
 	uv run python scripts/check_deprecated_names.py
+	uv run python scripts/check_github_contributor_docs.py
 	uv run python scripts/check_datetime_discipline.py
 	uv run python scripts/dump_openapi.py --check
 
 docs-check:
 	python3 scripts/check_docs.py
+	python3 scripts/check_github_contributor_docs.py
 	ruby -e 'require "yaml"; Dir[".github/ISSUE_TEMPLATE/*.yml"].sort.each { |p| YAML.load_file(p); puts "YAML ok: #{p}" }'
 
 check-commits:
@@ -61,6 +64,11 @@ check-assets:
 check-deprecated-names:
 	uv run python scripts/check_deprecated_names.py
 
+# GitHub contributor-doc gate. Public contribution guidance must target the
+# GitHub `main` workflow, not an internal branch model.
+check-github-docs:
+	uv run python scripts/check_github_contributor_docs.py
+
 # Advisory CJK scan (see .claude/rules/language-policy.md). Deliberately NOT
 # wired into `lint` / `ci`: the policy is enforced by review and the rules
 # doc, not a hard gate. Run on demand when touching potentially-CJK files.

QUICKSTART.md

@@ -10,15 +10,19 @@ front of your agent.
 ## Prerequisites
 
 - **Python 3.12+**
-- **An OpenRouter API key** — covers the chat LLM (memory extraction)
-  *and* the multimodal LLM (parsing image / pdf / audio content items)
-  with a single key.
-- **A DeepInfra API key** — for the embedding + rerank models that
-  OpenRouter doesn't ship.
-
-Two keys total. Any OpenAI-compatible endpoint plugs in via the
-matching `*__BASE_URL` env var if you'd rather use OpenAI directly,
-self-host vLLM, route to Ollama, etc.
+- **An LLM provider key and endpoint** — for memory extraction. OpenRouter,
+  OpenAI, and other OpenAI-compatible providers work when you set
+  `base_url`.
+- **A multimodal provider key and endpoint** — needed only when parsing
+  image / pdf / audio content items.
+- **Embedding and rerank provider keys and endpoints** — for search. DeepInfra
+  works for the embedding + rerank path; vLLM and DashScope are also supported
+  for rerank.
+
+Many deployments use two distinct keys by reusing one LLM key for `[llm]` and
+`[multimodal]`, and one DeepInfra key for `[embedding]` and `[rerank]`. Any
+setting can live in TOML or be overridden by the matching `EVEROS_*`
+environment variable.
 
 ## 1. Install
 
@@ -29,15 +33,15 @@ pip install everos
 
 ## 2. Configure
 
-Generate the starter config and drop in your two keys:
+Generate the starter config and fill in provider credentials:
 
 ```bash
 everos init                    # writes ~/.everos/everos.toml + ome.toml (use --root to relocate)
-# Edit ~/.everos/everos.toml and fill four api_key slots (only two distinct keys needed):
-#   [llm]        api_key   (OpenRouter — chat LLM)
-#   [multimodal] api_key   (OpenRouter — same key works)
-#   [embedding]  api_key   (DeepInfra)
-#   [rerank]     api_key   (DeepInfra — same key works)
+# Edit ~/.everos/everos.toml and fill the provider fields:
+#   [llm]        api_key + base_url             (chat LLM)
+#   [multimodal] api_key + base_url             (optional parser LLM)
+#   [embedding]  model + api_key + base_url
+#   [rerank]     model + api_key + base_url     (provider can be inferred or set)
 ```
 
 `everos init` generates two files: `everos.toml` (provider settings)
@@ -48,9 +52,9 @@ after editing: `chmod 600 ~/.everos/everos.toml`.
 The shipped template sets model defaults for `[llm]` (`gpt-4.1-mini`) and
 `[multimodal]` (`google/gemini-3-flash-preview`); `[embedding]` and
 `[rerank]` ship no model default — set `model` + `base_url` for those two
-sections yourself (e.g. DeepInfra's `Qwen/Qwen3-Embedding-4B` /
-`Qwen/Qwen3-Reranker-4B`). To use a different OpenAI-compatible endpoint
-for any provider, set the matching `base_url` field.
+sections yourself (for example DeepInfra's `Qwen/Qwen3-Embedding-4B` /
+`Qwen/Qwen3-Reranker-4B`). `[llm]` and `[multimodal]` ship model defaults,
+but still need `api_key` and `base_url` before those capabilities are used.
 
 > **Where config lives** — `everos init` writes into the memory root
 > (`~/.everos` by default; relocate with `everos init --root <path>` and

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported Versions
 
-EverOS is released and at v1.0.0 (stable). Security fixes are applied to the
+EverOS is released and in the v1.x stable line. Security fixes are applied to the
 latest release line only.
 
 | Version | Supported |
@@ -39,8 +39,9 @@ following in mind:
   is loopback-only. Only set the bind to `0.0.0.0` (or any routable interface)
   after you have placed your own gateway / auth layer in front;
   `everos server start` will log a warning when you bind to `0.0.0.0`.
-- Secrets (LLM / embedding API keys) live in your local `.env`; protect that
-  file as you would any credential. EverOS never transmits them anywhere except
-  the providers you configure.
+- Secrets (LLM / embedding / rerank API keys) normally live in your local
+  `<root>/everos.toml`, or in `EVEROS_*` environment variables for container
+  deployments. Protect those values as you would any credential. EverOS never
+  transmits them anywhere except the providers you configure.
 - Memory content is stored as plaintext `.md` files; apply OS-level file
   permissions or disk encryption if your data is sensitive.

docs/configuration.md

@@ -105,15 +105,15 @@ everos init --root /data/everos
 |---|---|---|---|---|
 | `model` | string | `"gpt-4.1-mini"` | No | LLM model identifier. |
 | `api_key` | string | — | **Yes** | API key for the LLM provider. |
-| `base_url` | string | — | No | Custom endpoint URL (OpenAI-compatible). |
+| `base_url` | string | — | **Yes** | Endpoint URL (OpenAI-compatible). |
 
 ### `[multimodal]`
 
 | Field | Type | Default | Required | Description |
 |---|---|---|---|---|
 | `model` | string | `"google/gemini-3-flash-preview"` | No | Multimodal parsing model. |
 | `api_key` | string | — | **Yes** | API key. |
-| `base_url` | string | — | No | Custom endpoint URL. |
+| `base_url` | string | — | **Yes** | Endpoint URL. |
 | `max_concurrency` | int | `4` | No | Max parallel parsing requests. |
 | `file_uri_allow_dirs` | list[string] | `[]` | No | Allowlisted base dirs for `file://` URIs. Empty = allow any readable file. |
 | `file_uri_max_bytes` | int | `52428800` | No | Max size (bytes) of a `file://` asset; larger files are rejected. |
@@ -134,7 +134,7 @@ everos init --root /data/everos
 
 | Field | Type | Default | Required | Description |
 |---|---|---|---|---|
-| `provider` | string | `"deepinfra"` | No | Rerank provider: `deepinfra` or `vllm`. |
+| `provider` | string | inferred | No | Rerank provider: `deepinfra`, `vllm`, or `dashscope`. |
 | `model` | string | — | **Yes** | Reranker model identifier. |
 | `api_key` | string | — | **Yes** | API key. |
 | `base_url` | string | — | **Yes** | Rerank endpoint URL. |
@@ -210,9 +210,13 @@ variables directly:
 ENV EVEROS_ROOT=/data/everos
 ENV EVEROS_LLM__API_KEY=sk-...
 ENV EVEROS_LLM__MODEL=gpt-4o
+ENV EVEROS_LLM__BASE_URL=https://api.openai.com/v1
 ENV EVEROS_EMBEDDING__MODEL=text-embedding-3-large
 ENV EVEROS_EMBEDDING__API_KEY=sk-...
 ENV EVEROS_EMBEDDING__BASE_URL=https://api.openai.com/v1
+ENV EVEROS_RERANK__MODEL=Qwen/Qwen3-Reranker-4B
+ENV EVEROS_RERANK__API_KEY=...
+ENV EVEROS_RERANK__BASE_URL=https://api.deepinfra.com/v1/inference
 ENV EVEROS_API__HOST=0.0.0.0
 ENV EVEROS_API__PORT=8000
 ```