exactdocs 0.1.1__tar.gz → 0.2.0__tar.gz

{exactdocs-0.1.1 → exactdocs-0.2.0}/.gitignore

@@ -12,6 +12,9 @@ coverage.xml
 htmlcov/
 reports/
 
+# Zensical output
+site/
+
 # Built web UI bundled into the wheel / image (see web/README.md)
 packages/exactdocs/src/exactdocs/_web/
 
@@ -31,3 +34,8 @@ Thumbs.db
 
 # Claude Code local settings
 .claude/settings.local.json
+
+# Browser end-to-end run (e2e/)
+e2e/test-results/
+e2e/shots/
+e2e/node_modules/

{exactdocs-0.1.1 → exactdocs-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: exactdocs
-Version: 0.1.1
+Version: 0.2.0
 Summary: Self-hosted, version-accurate documentation for AI coding agents (MCP server).
 Project-URL: Repository, https://github.com/SirCypkowskyy/ExactDocs
 Project-URL: Issues, https://github.com/SirCypkowskyy/ExactDocs/issues
@@ -12,13 +12,21 @@ Classifier: Framework :: FastAPI
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
+Requires-Dist: aiosqlite>=0.21
+Requires-Dist: alembic>=1.16
+Requires-Dist: argon2-cffi>=25
+Requires-Dist: cryptography>=46
 Requires-Dist: cyclopts>=4
-Requires-Dist: exactdocs-kernel==0.1.1
+Requires-Dist: exactdocs-kernel==0.2.0
 Requires-Dist: fastapi>=0.120
 Requires-Dist: fastmcp>=4
+Requires-Dist: markdown-it-py>=4
 Requires-Dist: mcp>=2
+Requires-Dist: platformdirs>=4
 Requires-Dist: pydantic-settings>=2.11
 Requires-Dist: pydantic>=2.12
+Requires-Dist: pyyaml>=6
+Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: uvicorn[standard]>=0.38
 Description-Content-Type: text/markdown
 

exactdocs-0.2.0/alembic.ini

@@ -0,0 +1,5 @@
+# Only for authoring revisions:  just migration "what changed"
+# (migrations run in code at startup, see exactdocs.bootstrap.database).
+[alembic]
+script_location = %(here)s/src/exactdocs/bootstrap/migrations
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s_%%(slug)s

exactdocs-0.2.0/features/add_library.feature

@@ -0,0 +1,55 @@
+Feature: Adding a library with its doc selection
+  As an admin
+  I want to create a library from a repository, choosing what to import and which ref
+  So that every import says exactly which commit it took
+
+  Background:
+    Given ExactDocs is running with the demo catalog
+
+  Scenario: Without a ref the default branch is imported
+    When a user adds the fixture repository with paths "docs/" and no ref
+    Then the library has a version for the default branch
+    And that version records the branch head commit SHA
+    And an import job is queued for that version
+
+  Scenario Outline: A tag, a branch or a commit is pinned to its commit
+    When a user adds the fixture repository with paths "docs/" and the ref "<ref>"
+    Then the version is "<ref>" and records the commit of "<commit>"
+
+    Examples:
+      | ref    | commit |
+      | v1.3.0 | v1.3.0 |
+      | next   | next   |
+
+  Scenario: A short commit SHA becomes the full one
+    When a user adds the fixture repository with paths "docs/" and the short SHA of "v1.4.0"
+    Then the version is the full SHA of "v1.4.0"
+
+  Scenario: An unknown ref creates nothing
+    When a user adds the fixture repository with paths "docs/" and the ref "v9.9.9"
+    Then the request fails with "unknown_ref"
+    And the library "/fixture/docs-repo" does not exist
+
+  Scenario: Exclusions are kept with the library and win over inclusions
+    When a user adds the fixture repository with paths "docs/**" and exclusion "docs/archive/**"
+    Then the library keeps the inclusion "docs/**" and the exclusion "docs/archive/**"
+
+  Scenario: Tag rules are kept with the library, normalized
+    When a user adds the fixture repository with paths "docs/**" and the tag rule "docs/api/** -> API"
+    Then the library keeps the tag rule "docs/api/** -> api"
+
+  Scenario: A tag rule that cannot work is refused
+    When a user adds the fixture repository with paths "docs/**" and the tag rule "docs/api/** -> not a tag!"
+    Then the request fails with "invalid_tag"
+
+  Scenario: A pattern that cannot work is refused
+    When a user adds the fixture repository with paths "../secrets" and no ref
+    Then the request fails with "invalid_path_pattern"
+
+  Scenario: A taken ID asks for another one
+    When a user adds the fixture repository as "/acme/payments"
+    Then the request fails with "library_id_taken"
+
+  Scenario: The picker lists the tags and branches
+    When a user lists the refs of the fixture repository
+    Then the default branch is "main", the branches are "main, next" and the tags are "v1.3.0, v1.4.0"

exactdocs-0.2.0/features/add_version.feature

@@ -0,0 +1,43 @@
+Feature: Adding another version to a library
+  As a team working on projects pinned to different releases
+  I want to add a version next to the ones a library has
+  So that every version is imported with exactly the same settings
+
+  Background:
+    Given ExactDocs imports the fixture docs repository
+
+  Scenario: A second version uses the library's settings
+    Given the fixture repository is imported at "v1.4.0" with paths "docs/**" excluding "docs/archive/**"
+    When the user adds the version "v1.3.0"
+    Then both "v1.3.0" and "v1.4.0" are listed
+    And "/fixture/docs-repo/v1.3.0" has the article "docs/guide/auth.md"
+    And "/fixture/docs-repo/v1.3.0" has no article "docs/archive/old-release.md"
+
+  Scenario: The answer points at the import job
+    Given "/fixture/docs-repo/v1.4.0" is imported
+    When the user adds the version "v1.3.0"
+    Then the response says the import was accepted and points to its job
+
+  Scenario: A newer release becomes the default version
+    Given "/fixture/docs-repo/v1.3.0" is imported
+    When the user adds the version "v1.4.0"
+    Then the default version is "v1.4.0"
+
+  Scenario: A branch does not take the default from a release
+    Given "/fixture/docs-repo/v1.4.0" is imported
+    When the user adds the version "next"
+    Then the default version is "v1.4.0"
+
+  Scenario: A version the library already has is refused
+    Given "/fixture/docs-repo/v1.4.0" is imported
+    When the user adds the version "v1.4.0"
+    Then adding the version fails with "version_exists"
+
+  Scenario: An unknown ref queues nothing
+    Given "/fixture/docs-repo/v1.4.0" is imported
+    When the user adds the version "v9.9.9"
+    Then adding the version fails with "unknown_ref"
+
+  Scenario: An unknown library is not found
+    When the user adds "v1.3.0" to the library "/nobody/nothing"
+    Then the library is not found

exactdocs-0.2.0/features/api.feature

@@ -0,0 +1,17 @@
+Feature: Versioned REST API
+  As a developer of the web UI or the CLI
+  I want one documented API with stable conventions
+  So that every client behaves the same against any instance
+
+  Background:
+    Given ExactDocs is running with the demo catalog
+
+  Scenario: The API describes itself
+    When I fetch the OpenAPI description
+    Then every operation has a stable operation ID and documented error responses
+
+  Scenario: Errors have one shape
+    When I request the library "/vuejs/docs"
+    Then the response status is 404
+    And the error code is "not_found"
+    And the error has a message

exactdocs-0.2.0/features/articles.feature

@@ -0,0 +1,90 @@
+Feature: Version manifests
+  As an AI coding agent
+  I want a version's articles to change all at once, never piece by piece
+  So that I never read half of a re-synced version
+
+  Background:
+    Given ExactDocs is running with the demo catalog
+    And "/acme/payments" version "main" has the active manifest at commit "aaa111":
+      | path               | title   | content          |
+      | guide/install.md   | Install | install, old     |
+      | guide/auth.md      | Auth    | auth             |
+      | api/client.md      | Client  | client           |
+
+  Scenario: Reading an article returns the active manifest, not a pending one
+    Given "/acme/payments" version "main" has a pending manifest at commit "bbb222":
+      | path               | title   | content          |
+      | guide/install.md   | Install | install, new     |
+    When I read the article "guide/install.md" of "/acme/payments" version "main"
+    Then the response status is 200
+    And the article says "install, old" at commit "aaa111"
+
+  Scenario: Activating a manifest swaps the whole version at once
+    Given "/acme/payments" version "main" has a pending manifest at commit "bbb222":
+      | path               | title   | content          |
+      | guide/install.md   | Install | install, new     |
+      | guide/new.md       | New     | brand new        |
+    When the pending manifest is activated
+    And I read the article "guide/install.md" of "/acme/payments" version "main"
+    Then the article says "install, new" at commit "bbb222"
+    When I list the articles of "/acme/payments" version "main"
+    Then the articles are "guide/install.md, guide/new.md" at commit "bbb222"
+    When I request the version "/acme/payments/main"
+    Then the version used is "main" of "/acme/payments"
+    And the commit of the version is "bbb222"
+
+  Scenario: Browsing without a ref uses the default version
+    Given "/acme/payments" version "v1.4.0" has the active manifest at commit "ccc333":
+      | path               | title   | content          |
+      | guide/install.md   | Install | install, v1.4    |
+    When I read the article "guide/install.md" of "/acme/payments" without a ref
+    Then the article says "install, v1.4" at commit "ccc333"
+
+  Scenario: Articles can be listed under a path prefix
+    When I list the articles under "guide/" of "/acme/payments" version "main"
+    Then the articles are "guide/auth.md, guide/install.md" at commit "aaa111"
+
+  Scenario: A long list is paged with a cursor
+    When I list 2 articles of "/acme/payments" version "main"
+    Then the articles are "api/client.md, guide/auth.md" at commit "aaa111"
+    And there is a next page
+
+  Scenario: An article that is not in the version is not found
+    When I read the article "guide/missing.md" of "/acme/payments" version "main"
+    Then the response status is 404
+    And the error code is "not_found"
+
+  Scenario: A version without an active manifest has no articles
+    When I read the article "guide/install.md" of "/acme/payments" version "next"
+    Then the response status is 404
+    And the error code is "not_found"
+
+  Scenario Outline: Listing filters by tags before paging
+    Given "/acme/payments" version "main" has the active manifest at commit "ddd444":
+      | path          | title | content | tags     |
+      | adr/0001.md   | ADR   | adr     | adr      |
+      | api/auth.md   | Auth  | auth    | api,auth |
+      | api/pay.md    | Pay   | pay     | api      |
+      | guide/faq.md  | FAQ   | faq     |          |
+    When I filter the articles of "/acme/payments" version "main" by <match> of tags "<tags>"
+    Then the articles are "<paths>" at commit "ddd444"
+
+    Examples:
+      | match | tags     | paths                           |
+      | any   | adr, API | adr/0001.md, api/auth.md, api/pay.md |
+      | all   | api,auth | api/auth.md                     |
+
+  Scenario: A filtered list is paged over the matches only
+    Given "/acme/payments" version "main" has the active manifest at commit "ddd444":
+      | path          | title | content | tags |
+      | a.md          | A     | a       |      |
+      | b.md          | B     | b       | api  |
+      | c.md          | C     | c       |      |
+      | d.md          | D     | d       | api  |
+    When I filter 1 articles of "/acme/payments" version "main" by any of tags "api"
+    Then the articles are "b.md" at commit "ddd444"
+    And there is a next page
+
+  Scenario: A filter that is not a tag is refused
+    When I filter the articles of "/acme/payments" version "main" by any of tags "not a tag!"
+    Then the response status is 422

exactdocs-0.2.0/features/catalog.feature

@@ -0,0 +1,43 @@
+Feature: Library catalog
+  As an AI coding agent
+  I want to address a library and a version by a predictable ID
+  So that I always get the version I asked for, never a plausible neighbour
+
+  Background:
+    Given ExactDocs is running with the demo catalog
+
+  Scenario: Listing indexed libraries shows each default version
+    When I list the libraries over the REST API
+    Then the response status is 200
+    And the libraries are:
+      | id             | versions                   | default version |
+      | /acme/ledger   | main                       | main            |
+      | /acme/payments | main, next, v1.3.0, v1.4.0 | v1.4.0          |
+
+  Scenario: A library ID without a ref means its default version
+    When I request the library "/acme/payments"
+    Then the response status is 200
+    And the default version of "/acme/payments" is "v1.4.0"
+
+  Scenario: The library ID is not case-sensitive
+    When I request the library "/Acme/Payments"
+    Then the default version of "/acme/payments" is "v1.4.0"
+
+  Scenario: A ref names exactly that version
+    When I request the version "/acme/payments/v1.3.0"
+    Then the version used is "v1.3.0" of "/acme/payments"
+
+  Scenario: Refs are case-sensitive and never approximated
+    When I request the version "/acme/payments/V1.3.0"
+    Then the response status is 404
+    And the error code is "not_found"
+
+  Scenario: A malformed ID is rejected
+    When I request the library "/acme/pay$ments"
+    Then the response status is 422
+    And the error code is "validation_error"
+
+  Scenario: Asking for a library that is not indexed
+    When I request the library "/vuejs/docs"
+    Then the response status is 404
+    And the error code is "not_found"

exactdocs-0.2.0/features/chunking.feature

@@ -0,0 +1,24 @@
+Feature: Heading-based chunks
+  As an AI coding agent
+  I want articles cut at their headings and never inside a code block or table
+  So that a search result is a section I can use as it is
+
+  Background:
+    Given the fixture docs repository is built and served
+
+  Scenario: A section is addressed by its heading path
+    When I chunk "docs/guide/install.md" of version "v1.4.0"
+    Then there is a chunk with the heading path "Guide > Install > Docker"
+    And that chunk keeps its fenced "bash" block whole
+
+  Scenario: The install table stays in one chunk
+    When I chunk "docs/guide/install.md" of version "v1.4.0"
+    Then the chunk "Guide > Install" holds the whole platform table
+
+  Scenario: Repeated headings are told apart
+    When I chunk "docs/guide/install.md" of version "v1.4.0"
+    Then the chunks "Guide > Install > Docker > Troubleshooting" and "Guide > Install > From source > Troubleshooting" have anchors "troubleshooting" and "troubleshooting-1"
+
+  Scenario: A parser change re-chunks
+    Given the parser version is bumped
+    Then the chunking-config hash differs from before

exactdocs-0.2.0/features/chunks.feature

@@ -0,0 +1,61 @@
+Feature: Version-scoped chunk IDs
+  As an AI coding agent
+  I want a chunk ID to name exactly one chunk of one version
+  So that read_chunk is unambiguous and an ID survives a re-sync when its section did not change
+
+  Background:
+    Given ExactDocs is running with the demo catalog
+
+  Scenario: An unchanged article keeps its chunk IDs when the branch is re-synced
+    Given "/acme/payments" version "main" is indexed as "first" at commit "aaa111":
+      | path             | text       |
+      | guide/auth.md    | auth       |
+      | guide/install.md | install v1 |
+    When "/acme/payments" version "main" is indexed as "second" at commit "bbb222":
+      | path             | text       |
+      | guide/auth.md    | auth       |
+      | guide/install.md | install v2 |
+    Then every chunk of "guide/auth.md" has the same ID in "first" and "second"
+    And no chunk of "guide/install.md" has the same ID in "first" and "second"
+
+  Scenario: The same content in two versions is stored once under different chunk IDs
+    Given "/acme/payments" version "v1.3.0" is indexed as "old" at commit "aaa111":
+      | path             | text    |
+      | guide/install.md | install |
+    When "/acme/payments" version "v1.4.0" is indexed as "new" at commit "bbb222":
+      | path             | text    |
+      | guide/install.md | install |
+    Then "new" stored no chunk set of its own
+    And no chunk of "guide/install.md" has the same ID in "old" and "new"
+
+  Scenario: Indexing the same manifest twice stores nothing new
+    Given "/acme/payments" version "main" is indexed as "first" at commit "aaa111":
+      | path             | text    |
+      | guide/install.md | install |
+    When the manifest "first" is indexed again
+    Then nothing new was stored
+    And every chunk of "guide/install.md" has the same ID in "first" and "first again"
+
+  Scenario: A chunk can be read only once its manifest is active
+    Given "/acme/payments" version "main" is indexed as "first" at commit "aaa111":
+      | path             | text    |
+      | guide/install.md | install |
+    When I read the second chunk of "guide/install.md" in "first"
+    Then the chunk cannot be found
+    When the manifest "first" is activated
+    And I read the second chunk of "guide/install.md" in "first"
+    Then the chunk says "install two" and its previous chunk is the first one
+
+  Scenario: A chunk ID from a superseded manifest says it is stale
+    Given "/acme/payments" version "main" is indexed as "first" at commit "aaa111":
+      | path             | text       |
+      | guide/install.md | install v1 |
+    When the manifest "first" is activated
+    And "/acme/payments" version "main" is indexed as "second" at commit "bbb222":
+      | path             | text       |
+      | guide/install.md | install v2 |
+    When the manifest "second" is activated
+    And I read the second chunk of "guide/install.md" in "first"
+    Then the chunk is stale and says how to find the current one
+    When I read the second chunk of "guide/install.md" in "second"
+    Then the chunk says "install v2 two" and its previous chunk is the first one

exactdocs-0.2.0/features/environment.py

@@ -0,0 +1,25 @@
+"""Behave hooks: build the fixture docs repository once per run and serve it on 127.0.0.1."""
+
+import sys
+import tempfile
+from contextlib import ExitStack
+from importlib import import_module
+from pathlib import Path
+
+from behave.runner import Context
+
+# The fixture builder is test support shared with pytest, not part of the package. behave has no
+# pythonpath option; import_module keeps ruff (E402) and ty from needing the path at lint time.
+sys.path.insert(0, str(Path(__file__).parents[1] / "tests" / "fixtures"))
+fixture_repo = import_module("fixture_repo")
+
+
+def before_all(context: Context) -> None:
+    context.stack = ExitStack()
+    base = Path(context.stack.enter_context(tempfile.TemporaryDirectory(prefix="exactdocs-fx-")))
+    context.fixture_repo = context.stack.enter_context(fixture_repo.served(base))
+    context.fixture_git = fixture_repo.git
+
+
+def after_all(context: Context) -> None:
+    context.stack.close()

exactdocs-0.2.0/features/fixture_repo.feature

@@ -0,0 +1,18 @@
+Feature: A versioned fixture docs repository
+  Import and search are asserted against one stable git repository, served over both transports
+  that the importer supports.
+
+  Background:
+    Given the fixture docs repository is built and served
+
+  Scenario Outline: Both git servers advertise the same versions
+    When I list the remote refs of the fixture repository over <transport>
+    Then the remote has the tags "v1.3.0, v1.4.0" and the branch "next"
+
+    Examples:
+      | transport |
+      | file      |
+      | http      |
+
+  Scenario: An identifier exists in one version only
+    Then "retry_policy" occurs in version "v1.4.0" but not in version "v1.3.0"

exactdocs-0.2.0/features/import.feature

@@ -0,0 +1,51 @@
+Feature: An import publishes a complete version or nothing
+  As an AI coding agent
+  I want a version to appear all at once, with the commit it was imported from
+  So that I never read half of a version, and a failed import never hides what was served before
+
+  Background:
+    Given ExactDocs imports the fixture docs repository
+
+  Scenario: An import publishes the whole version at once
+    When "docs/" of the fixture repository at "v1.3.0" is imported
+    Then the import succeeds and reports every file as processed
+    And "/fixture/docs-repo/v1.3.0" lists every selected article
+    And every article and chunk carries the commit SHA of "v1.3.0"
+
+  Scenario: One bad file does not fail the import
+    When "docs/" of the fixture repository at "v1.3.0" is imported
+    Then the import succeeds
+    And the job lists these skipped files:
+      | path                        | code        | reason                              |
+      | docs/legacy/binary.md       | binary      | binary file                         |
+      | docs/legacy/undecodable.md  | undecodable | not text in any supported encoding  |
+      | docs/reference/oversized.md | too_large   | larger than 2097152 bytes           |
+
+  Scenario: A Latin-1 file is decoded, not skipped
+    When "docs/" of the fixture repository at "v1.3.0" is imported
+    Then the article "docs/legacy/latin1.md" of "/fixture/docs-repo/v1.3.0" keeps its accented characters
+
+  Scenario: A failed import leaves the previous state served
+    Given "/fixture/docs-repo/next" is imported
+    When a re-import of "next" fails before activation
+    Then "/fixture/docs-repo/next" still serves the previous commit
+
+  Scenario: Versions stay apart
+    Given "/fixture/docs-repo/v1.3.0" is imported
+    When "docs/" of the fixture repository at "v1.4.0" is imported
+    Then "/fixture/docs-repo/v1.4.0" has the article "docs/guide/resilience.md"
+    And "/fixture/docs-repo/v1.3.0" has no article "docs/guide/resilience.md"
+
+  Scenario: Re-importing a commit changes nothing
+    Given "/fixture/docs-repo/v1.3.0" is imported
+    When "v1.3.0" is imported again
+    Then "/fixture/docs-repo/v1.3.0" lists the same articles and chunks as before
+
+  Scenario: Exclusions win over inclusions
+    When "docs/**" of the fixture repository at "v1.3.0" is imported excluding "docs/archive/**"
+    Then "/fixture/docs-repo/v1.3.0" has no article "docs/archive/old-release.md"
+    And "/fixture/docs-repo/v1.3.0" has the article "docs/guide/auth.md"
+
+  Scenario: Front-matter and path-rule tags combine
+    When "docs/**" of the fixture repository at "v1.3.0" is imported with the tag rule "docs/api/** -> api"
+    Then the article "docs/api/auth.md" of "/fixture/docs-repo/v1.3.0" is tagged "api" and "auth"

exactdocs-0.2.0/features/ingestion.feature

@@ -0,0 +1,53 @@
+Feature: Safe article parsing
+  As an AI coding agent
+  I want article titles to be right and hidden instructions to be gone
+  So that I can trust what I read from a doc repository
+
+  Scenario: The article title follows front matter, then H1, then file name
+    Given the article "guide/install.md":
+      """
+      ---
+      title: Install ExactDocs
+      ---
+      # Getting started
+      """
+    And the article "guide/auth.md":
+      """
+      # Authentication
+      """
+    And the article "notes.md":
+      """
+      Just some notes.
+      """
+    When the articles are imported
+    Then the title of "guide/install.md" is "Install ExactDocs"
+    And the title of "guide/auth.md" is "Authentication"
+    And the title of "notes.md" is "notes"
+
+  Scenario: Hidden characters are removed on import
+    Given the article "hidden.md" contains a zero-width space and a bidi override
+    When the articles are imported
+    Then the stored Markdown of "hidden.md" contains neither
+    And the stored Markdown of "hidden.md" is otherwise identical to the source
+
+  Scenario: Malformed front matter does not stop the import
+    Given the article "broken.md":
+      """
+      ---
+      title: [unclosed
+      ---
+      # Still here
+      """
+    When the articles are imported
+    Then the title of "broken.md" is "Still here"
+    And "broken.md" is listed with the problem "malformed front matter"
+
+  Scenario: MDX components are kept as text
+    Given the article "tabs.mdx":
+      """
+      import { Tabs } from '@site/components'
+
+      <Tabs>npm i exactdocs</Tabs>
+      """
+    When the articles are imported
+    Then the stored Markdown of "tabs.mdx" is identical to the source

exactdocs-0.2.0/features/jobs.feature

@@ -0,0 +1,26 @@
+Feature: Background jobs
+  As someone importing a large documentation repository
+  I want long tasks to run in the background and show how far they got
+  So that a request never blocks and I can tell a slow import from a stuck one
+
+  Background:
+    Given ExactDocs is running
+
+  Scenario: Seeing how far a job got
+    Given a job over 10 files of "/acme/payments" that has finished 4
+    When I request that job
+    Then the response status is 200
+    And the job is running with 4 of 10 files done
+
+  Scenario: Listing the jobs of a library, newest first
+    Given a finished job "job-1" of "/acme/payments"
+    And a finished job "job-2" of "/acme/payments"
+    And a finished job "job-3" of "/acme/ledger"
+    When I list the jobs of the library "/acme/payments"
+    Then the response status is 200
+    And the jobs are, newest first: "job-2", "job-1"
+
+  Scenario: Asking for a job that does not exist
+    When I request the job "no-such-job"
+    Then the response status is 404
+    And the error code is "not_found"

exactdocs-0.2.0/features/library_readme.feature

@@ -0,0 +1,24 @@
+Feature: A library gets its title and description from the root README
+  As an AI coding agent
+  I want libraries to carry a meaningful title and description
+  So that I can pick the right library in "resolve-library-id" without anyone typing them
+
+  Background:
+    Given ExactDocs imports the fixture docs repository
+
+  Scenario: Defaults come from the root README even outside the selection
+    When "docs/" of the fixture repository at "v1.3.0" is imported
+    Then the title of the library is the first heading of the README
+    And the description of the library is the first paragraph of the README
+
+  Scenario: The user can edit them
+    Given "/fixture/docs-repo/v1.3.0" is imported
+    When the user changes the title to "Payments SDK"
+    Then "list_libraries" shows the title "Payments SDK"
+
+  Scenario: An edited title survives a re-import
+    Given "/fixture/docs-repo/v1.3.0" is imported
+    And the user changes the title to "Payments SDK"
+    When "v1.3.0" is imported again
+    Then the title of the library is "Payments SDK"
+    And the description of the library is the first paragraph of the README

exactdocs-0.2.0/features/login.feature

@@ -0,0 +1,47 @@
+Feature: Admin session
+  As the admin of an instance
+  I want to sign in to the web UI with a session that expires and cannot be stolen by script
+  So that only I can use the instance from a browser
+
+  Background:
+    Given a fresh instance
+    And the admin "ada" was set up with the password "correct horse battery staple"
+
+  Scenario: Signing in and out
+    Then the libraries are not reachable
+    When the admin signs in with the password "correct horse battery staple"
+    Then the UI session is active for "ada"
+    And the session cookie is HttpOnly and SameSite=Lax
+    And the libraries are reachable
+    When the admin signs out
+    Then the libraries are no longer reachable with that session
+    And the UI session is not active
+
+  Scenario: A wrong password and an unknown user are told apart by nobody
+    When the admin signs in with the password "wrong horse battery staple"
+    Then the sign-in is refused with "invalid_credentials"
+    When "nobody" signs in with the password "correct horse battery staple"
+    Then the sign-in is refused with "invalid_credentials"
+    And no session cookie was set
+
+  Scenario: A session cookie never authenticates MCP
+    Given the admin is signed in to the UI
+    When the browser calls the MCP endpoint with the session cookie only
+    Then the MCP endpoint treats the call exactly like one without the cookie
+
+  Scenario: Another site cannot sign the admin in or out
+    Given the admin is signed in to the UI
+    When a page on "https://evil.example" signs the admin out
+    Then the request is forbidden
+    And the libraries are reachable
+    When a page on "https://evil.example" signs in with the password "correct horse battery staple"
+    Then the request is forbidden
+
+  Scenario: Resetting the password signs the admin out everywhere
+    Given the admin is signed in to the UI
+    When the operator runs "exactdocs admin reset-password" with the username "ada" and the password "a brand new passphrase"
+    Then the libraries are no longer reachable with that session
+    When the admin signs in with the password "correct horse battery staple"
+    Then the sign-in is refused with "invalid_credentials"
+    When the admin signs in with the password "a brand new passphrase"
+    Then the UI session is active for "ada"