chore: initialize EverOS 1.0.0

md-first memory extraction framework for AI agents.

Markdown is the single source of truth; SQLite holds state and LanceDB
provides the rebuildable vector + BM25 + scalar index. The codebase follows
a single-direction DDD layering (entrypoints -> service -> memory -> infra,
with component / core / config cross-cutting) enforced by import-linter.

Engineering surface:
- Coding conventions in .claude/rules/ (path-scoped) and workflows in
  .claude/skills/ (/commit, /new-branch, /pr).
- GitHub Actions CI runs make lint + test + integration; pre-commit mirrors
  the gates locally (ruff, hygiene hooks, gitlint commit-msg).
- Commit messages follow Conventional Commits, enforced by gitlint.
- make lint also enforces datetime two-zone discipline and OpenAPI drift.

tests/unit/test_entrypoints/test_cli/test_cascade_command.py

@@ -0,0 +1,98 @@
+"""``everos cascade`` — structural smoke + pure helper tests.
+
+The orchestrator paths require live sqlite + lancedb singletons; those
+are exercised by integration tests. Here we cover:
+
+- subcommand registration (sync / status / fix)
+- ``--help`` exit codes
+- ``_resolve_relative`` (path arithmetic vs. memory root)
+- ``_print_failed_table`` (formatting of failed rows)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from everos.entrypoints.cli.commands import cascade as cascade_mod
+
+
+def test_app_registers_three_commands() -> None:
+    names = {cmd.name for cmd in cascade_mod.app.registered_commands}
+    assert names == {"sync", "status", "fix"}
+
+
+def test_help_exits_zero() -> None:
+    result = CliRunner().invoke(cascade_mod.app, ["--help"])
+    assert result.exit_code == 0
+    assert "sync" in result.stdout
+    assert "status" in result.stdout
+    assert "fix" in result.stdout
+
+
+def test_resolve_relative_under_root(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("EVEROS_MEMORY__ROOT", str(tmp_path))
+    from everos.config import load_settings
+
+    load_settings.cache_clear()
+
+    rel = cascade_mod._resolve_relative(tmp_path / "users" / "u1" / "x.md")
+    assert rel == "users/u1/x.md"
+
+
+def test_resolve_relative_outside_root_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("EVEROS_MEMORY__ROOT", str(tmp_path / "memory"))
+    from everos.config import load_settings
+
+    load_settings.cache_clear()
+
+    other = tmp_path / "somewhere-else.md"
+    with pytest.raises(typer.BadParameter, match="not under memory root"):
+        cascade_mod._resolve_relative(other)
+
+
+@dataclass
+class _FailedRow:
+    md_path: str
+    retryable: bool
+    retry_count: int
+    last_attempt_at: object
+    error: str | None
+
+
+def test_print_failed_table_formats_rows(capsys: pytest.CaptureFixture[str]) -> None:
+    from datetime import UTC, datetime
+
+    rows = [
+        _FailedRow(
+            md_path="users/u1/a.md",
+            retryable=True,
+            retry_count=2,
+            last_attempt_at=datetime(2026, 1, 1, tzinfo=UTC),
+            error="boom",
+        ),
+        _FailedRow(
+            md_path="users/u2/b.md",
+            retryable=False,
+            retry_count=5,
+            last_attempt_at=None,
+            error=None,
+        ),
+    ]
+    cascade_mod._print_failed_table(rows)  # type: ignore[arg-type]
+    out = capsys.readouterr().out
+    assert "2 failed row(s):" in out
+    assert "users/u1/a.md" in out
+    assert "TRUE" in out
+    assert "users/u2/b.md" in out
+    assert "FALSE" in out
+    # Header row present
+    assert "md_path" in out and "retries" in out

tests/unit/test_entrypoints/test_cli/test_init_command.py

@@ -0,0 +1,213 @@
+"""``everos init`` — CLI behavior + edge cases.
+
+Covers:
+
+- default ``./.env`` path, written with 0600 permissions
+- ``--to <path>`` creates parent dirs
+- ``--force`` overwrites; without it the command refuses with exit 1
+- ``--print`` writes to stdout, NOT to disk
+- ``--xdg`` and ``--to`` are mutually exclusive (exit 2)
+- ``--xdg`` honors ``XDG_CONFIG_HOME``
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from everos.entrypoints.cli.main import app
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+@pytest.fixture
+def in_tmp(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Run from a fresh tmp cwd so default ``./.env`` lands in tmp_path."""
+    monkeypatch.chdir(tmp_path)
+    return tmp_path
+
+
+def test_default_writes_dotenv_in_cwd(runner: CliRunner, in_tmp: Path) -> None:
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code == 0, result.output
+    written = in_tmp / ".env"
+    assert written.exists()
+    assert written.stat().st_size > 0
+    assert "EVEROS_LLM__API_KEY" in written.read_text()
+
+
+def test_default_file_permissions_are_0600(runner: CliRunner, in_tmp: Path) -> None:
+    """The generated .env holds API keys — must not be world-readable."""
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code == 0
+    mode = stat.S_IMODE((in_tmp / ".env").stat().st_mode)
+    assert mode == 0o600, f"expected 0o600, got {oct(mode)}"
+
+
+def test_refuses_overwrite_without_force(runner: CliRunner, in_tmp: Path) -> None:
+    (in_tmp / ".env").write_text("PREEXISTING=1\n")
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code == 1
+    assert "already exists" in (result.output + (result.stderr or ""))
+    # Original content must be preserved.
+    assert (in_tmp / ".env").read_text() == "PREEXISTING=1\n"
+
+
+def test_force_overwrites(runner: CliRunner, in_tmp: Path) -> None:
+    (in_tmp / ".env").write_text("PREEXISTING=1\n")
+    result = runner.invoke(app, ["init", "--force"])
+    assert result.exit_code == 0
+    body = (in_tmp / ".env").read_text()
+    assert "PREEXISTING=1" not in body
+    assert "EVEROS_LLM__API_KEY" in body
+
+
+def test_to_creates_parent_dirs(runner: CliRunner, in_tmp: Path) -> None:
+    target = in_tmp / "nested" / "subdir" / ".env"
+    result = runner.invoke(app, ["init", "--to", str(target)])
+    assert result.exit_code == 0
+    assert target.exists()
+    assert "EVEROS_LLM__API_KEY" in target.read_text()
+
+
+def test_print_writes_stdout_not_disk(runner: CliRunner, in_tmp: Path) -> None:
+    result = runner.invoke(app, ["init", "--print"])
+    assert result.exit_code == 0
+    assert "EVEROS_LLM__API_KEY" in result.output
+    # No disk side-effect.
+    assert not (in_tmp / ".env").exists()
+
+
+def test_xdg_writes_to_xdg_config_home(
+    runner: CliRunner, in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    xdg_root = in_tmp / "xdg"
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg_root))
+    result = runner.invoke(app, ["init", "--xdg"])
+    assert result.exit_code == 0
+    target = xdg_root / "everos" / ".env"
+    assert target.exists()
+
+
+def test_xdg_falls_back_to_dot_config(
+    runner: CliRunner, in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """No ``XDG_CONFIG_HOME`` → default ``~/.config``.
+
+    We sandbox ``$HOME`` to ``in_tmp`` so the test does not touch a real
+    user's ``~/.config``.
+    """
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("HOME", str(in_tmp))
+    result = runner.invoke(app, ["init", "--xdg"])
+    assert result.exit_code == 0
+    target = in_tmp / ".config" / "everos" / ".env"
+    assert target.exists()
+
+
+def test_xdg_and_to_are_mutually_exclusive(runner: CliRunner, in_tmp: Path) -> None:
+    result = runner.invoke(app, ["init", "--xdg", "--to", str(in_tmp / "other.env")])
+    assert result.exit_code == 2
+    assert "mutually exclusive" in (result.output + (result.stderr or ""))
+
+
+def test_template_resource_is_packaged_under_everos_templates() -> None:
+    """The packaged resource must remain at the canonical location.
+
+    Guards the wheel/sdist layout: ``init_cmd`` reads
+    ``everos.templates.env.template`` via ``importlib.resources``; if
+    someone moves the file without updating ``_TEMPLATE_PACKAGE``, this
+    test fails immediately.
+    """
+    from importlib import resources
+
+    res = resources.files("everos.templates").joinpath("env.template")
+    assert res.is_file()
+    body = res.read_text(encoding="utf-8")
+    assert "EVEROS_LLM__API_KEY" in body
+
+
+# ── 4-layer .env resolution for ``server start`` ────────────────────────
+
+
+def test_resolve_env_file_explicit_wins(in_tmp: Path) -> None:
+    """``--env-file <path>`` beats cwd / XDG / ~/.everos fallbacks."""
+    from everos.entrypoints.cli.commands.server import _resolve_env_file
+
+    explicit = in_tmp / "explicit.env"
+    explicit.write_text("X=1\n")
+    # Also seed cwd .env so we can prove the explicit wins.
+    (in_tmp / ".env").write_text("CWD=1\n")
+    resolved = _resolve_env_file(str(explicit))
+    assert resolved == explicit
+
+
+def test_resolve_env_file_cwd_wins_over_xdg(
+    in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from everos.entrypoints.cli.commands.server import _resolve_env_file
+
+    xdg_root = in_tmp / "xdg"
+    (xdg_root / "everos").mkdir(parents=True)
+    (xdg_root / "everos" / ".env").write_text("XDG=1\n")
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg_root))
+    cwd_env = in_tmp / ".env"
+    cwd_env.write_text("CWD=1\n")
+    resolved = _resolve_env_file(None)
+    assert resolved == cwd_env
+
+
+def test_resolve_env_file_xdg_when_no_cwd(
+    in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from everos.entrypoints.cli.commands.server import _resolve_env_file
+
+    xdg_root = in_tmp / "xdg"
+    (xdg_root / "everos").mkdir(parents=True)
+    target = xdg_root / "everos" / ".env"
+    target.write_text("XDG=1\n")
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg_root))
+    # No cwd/.env.
+    resolved = _resolve_env_file(None)
+    assert resolved == target
+
+
+def test_resolve_env_file_everos_home_fallback(
+    in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """``~/.everos/.env`` is the last fallback when nothing else exists."""
+    from everos.entrypoints.cli.commands.server import _resolve_env_file
+
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("HOME", str(in_tmp))
+    target = in_tmp / ".everos" / ".env"
+    target.parent.mkdir(parents=True)
+    target.write_text("EVEROS_ROOT=1\n")
+    resolved = _resolve_env_file(None)
+    assert resolved == target
+
+
+def test_resolve_env_file_none_when_no_layer_matches(
+    in_tmp: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """All four layers absent → ``None`` (the server then falls back to
+    inherited process env, which is the documented CI/container path)."""
+    from everos.entrypoints.cli.commands.server import _resolve_env_file
+
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("HOME", str(in_tmp))
+    # Nothing in cwd, no XDG path, no ~/.everos/.
+    assert not (in_tmp / ".env").exists()
+    assert _resolve_env_file(None) is None
+
+
+# ``os`` imported above just to keep ruff from complaining; remove if Ruff
+# F401 hits.
+_ = os

tests/unit/test_entrypoints/test_cli/test_main.py

@@ -0,0 +1,22 @@
+"""CLI root app — verifies sub-typer wiring + ``--help`` exit code."""
+
+from __future__ import annotations
+
+from typer.testing import CliRunner
+
+from everos.entrypoints.cli.main import app
+
+
+def test_help_exits_zero() -> None:
+    result = CliRunner().invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "everos" in result.stdout
+    assert "server" in result.stdout
+    assert "cascade" in result.stdout
+
+
+def test_no_args_shows_help_and_exits_nonzero() -> None:
+    # ``no_args_is_help=True`` triggers a help exit with code 2 (typer default).
+    result = CliRunner().invoke(app, [])
+    assert result.exit_code != 0
+    assert "Usage" in result.stdout or "Usage" in result.stderr

tests/unit/test_entrypoints/test_cli/test_server_command.py

@@ -0,0 +1,134 @@
+"""``everos server start`` — argument resolution + uvicorn handoff.
+
+Uvicorn ``run`` is the external boundary and is mocked. We assert the
+host/port/log_level resolution chain (CLI flag > env > default) and the
+KeyboardInterrupt / OSError exit paths.
+"""
+
+from __future__ import annotations
+
+import pytest
+from typer.testing import CliRunner
+
+from everos.entrypoints.cli.commands import server as server_mod
+from everos.entrypoints.cli.main import app as root_app
+
+
+@pytest.fixture
+def captured(monkeypatch: pytest.MonkeyPatch) -> dict[str, object]:
+    """Mock ``uvicorn.run`` and return the kwargs it was called with."""
+    captured: dict[str, object] = {}
+
+    def fake_run(*args: object, **kwargs: object) -> None:
+        captured["args"] = args
+        captured["kwargs"] = kwargs
+
+    monkeypatch.setattr(server_mod.uvicorn, "run", fake_run)
+    # Strip env so default resolution path is deterministic.
+    for k in ("EVEROS_HOST", "EVEROS_PORT", "EVEROS_LOG_LEVEL"):
+        monkeypatch.delenv(k, raising=False)
+    return captured
+
+
+# Typer lifts single-command sub-apps to root; we invoke via the real
+# ``everos server start`` path through the assembled root app.
+
+
+def test_start_uses_default_host_port_log_level(captured: dict[str, object]) -> None:
+    result = CliRunner().invoke(
+        root_app, ["server", "start", "--env-file", "/nonexistent"]
+    )
+    assert result.exit_code == 0, result.stdout
+    kwargs = captured["kwargs"]
+    assert isinstance(kwargs, dict)
+    assert kwargs["host"] == "127.0.0.1"
+    assert kwargs["port"] == 8000
+    assert kwargs["log_level"] == "info"
+    assert kwargs["factory"] is True
+    args = captured["args"]
+    assert args == ("everos.entrypoints.api.app:create_app",)
+
+
+def test_start_cli_flags_override_env(
+    captured: dict[str, object], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("EVEROS_API__HOST", "1.2.3.4")
+    monkeypatch.setenv("EVEROS_API__PORT", "9000")
+    monkeypatch.setenv("EVEROS_API__LOG_LEVEL", "debug")
+    result = CliRunner().invoke(
+        root_app,
+        [
+            "server",
+            "start",
+            "--env-file",
+            "/nonexistent",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            "8765",
+            "--log-level",
+            "warning",
+        ],
+    )
+    assert result.exit_code == 0, result.stdout
+    kwargs = captured["kwargs"]
+    assert isinstance(kwargs, dict)
+    assert kwargs["host"] == "127.0.0.1"
+    assert kwargs["port"] == 8765
+    assert kwargs["log_level"] == "warning"
+
+
+def test_start_falls_back_to_env_when_flags_omitted(
+    captured: dict[str, object], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("EVEROS_API__HOST", "10.0.0.1")
+    monkeypatch.setenv("EVEROS_API__PORT", "8765")
+    result = CliRunner().invoke(
+        root_app, ["server", "start", "--env-file", "/nonexistent"]
+    )
+    assert result.exit_code == 0, result.stdout
+    kwargs = captured["kwargs"]
+    assert isinstance(kwargs, dict)
+    assert kwargs["host"] == "10.0.0.1"
+    assert kwargs["port"] == 8765
+
+
+def test_start_swallows_keyboard_interrupt(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(*args: object, **kwargs: object) -> None:
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(server_mod.uvicorn, "run", boom)
+    result = CliRunner().invoke(
+        root_app, ["server", "start", "--env-file", "/nonexistent"]
+    )
+    # KeyboardInterrupt path returns normally — exit 0.
+    assert result.exit_code == 0
+
+
+def test_start_exits_one_on_os_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(*args: object, **kwargs: object) -> None:
+        raise OSError("port in use")
+
+    monkeypatch.setattr(server_mod.uvicorn, "run", boom)
+    result = CliRunner().invoke(
+        root_app, ["server", "start", "--env-file", "/nonexistent"]
+    )
+    assert result.exit_code == 1
+
+
+def test_load_env_file_missing_path_is_noop(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    # Function should not raise when the file does not exist.
+    server_mod._load_env_file(str(tmp_path / "does-not-exist.env"))
+
+
+def test_load_env_file_reads_present_file(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.delenv("EVEROS_TEST_DOTENV_VAR", raising=False)
+    env_file = tmp_path / ".env"
+    env_file.write_text("EVEROS_TEST_DOTENV_VAR=loaded\n")
+    server_mod._load_env_file(str(env_file))
+    import os
+
+    assert os.environ.get("EVEROS_TEST_DOTENV_VAR") == "loaded"
+    monkeypatch.delenv("EVEROS_TEST_DOTENV_VAR", raising=False)