fcontext 1.0.2__tar.gz → 1.0.3__tar.gz

fcontext-1.0.3/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Test & Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs
+        run: pip install mkdocs-material mkdocs-mermaid-zoom
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

fcontext-1.0.3/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ['v*', '[0-9]*']
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fcontext-1.0.3/.gitignore

@@ -0,0 +1,33 @@
+# setuptools-scm generated version file
+fcontext/_version.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MkDocs
+site/

{fcontext-1.0.2 → fcontext-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcontext
-Version: 1.0.2
+Version: 1.0.3
 Summary: Context continuity across AI agents & sessions. Team knowledge collaboration. Industrial-grade AI delivery.
 License: Apache-2.0
 Requires-Python: >=3.9

fcontext-1.0.3/docs/architecture.md

@@ -0,0 +1,137 @@
+# Architecture
+
+## How fcontext Works
+
+fcontext operates on one principle: **structured local files that AI agents already know how to read**.
+
+```mermaid
+graph LR
+    subgraph "Your Project"
+        SRC["Source Code"]
+        DOCS["Documents<br/>PDF / DOCX / XLSX"]
+    end
+
+    subgraph ".fcontext/"
+        README["_README.md<br/>Project Summary"]
+        MAP["_workspace.map<br/>Structure"]
+        CACHE["_cache/<br/>Converted Docs"]
+        TOPICS["_topics/<br/>Session Knowledge"]
+        REQ["_requirements/<br/>Stories & Tasks"]
+        EXP["_experiences/<br/>Imported Packs"]
+    end
+
+    subgraph "Agent Configs"
+        GH[".github/instructions/"]
+        CL[".claude/rules/"]
+        CU[".cursor/rules/"]
+        TR[".trae/rules/"]
+    end
+
+    SRC --> |fcontext init| README
+    SRC --> |fcontext init| MAP
+    DOCS --> |fcontext index| CACHE
+
+    README --> |fcontext enable| GH
+    README --> |fcontext enable| CL
+    README --> |fcontext enable| CU
+    README --> |fcontext enable| TR
+```
+
+---
+
+## Directory Structure
+
+```
+.fcontext/
+├── _README.md            # Living project summary (AI-maintained)
+├── _workspace.map        # Auto-generated project structure
+├── _cache/               # Binary → Markdown conversions
+│   ├── specs/
+│   │   └── requirements.pdf.md
+│   └── docs/
+│       └── architecture.docx.md
+├── _topics/              # Session-accumulated knowledge
+│   ├── auth-analysis.md
+│   └── deploy-notes.md
+├── _requirements/        # Structured requirement tracking
+│   ├── STORY-001.yaml
+│   └── TASK-001.yaml
+└── _experiences/         # Imported knowledge packs (read-only)
+    └── domain-knowledge/
+        ├── _README.md
+        ├── _cache/
+        └── _topics/
+```
+
+---
+
+## Data Flow
+
+### Session Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant Agent as AI Agent
+    participant FC as .fcontext/
+
+    Dev->>Agent: Start session
+    Agent->>FC: Read _README.md
+    Agent->>FC: Read _workspace.map
+    Agent->>FC: Read _topics/
+    Agent->>FC: Read _requirements/
+    Agent->>FC: Read _experiences/
+
+    Note over Agent: Full context loaded
+
+    Dev->>Agent: Ask question / Give task
+    Agent->>Agent: Work with full context
+    Agent->>FC: Write _topics/new-insight.md
+    Agent->>FC: Update _README.md
+
+    Note over FC: Knowledge persisted
+
+    Dev->>Agent: Next session (same or different agent)
+    Agent->>FC: Read updated context
+    Note over Agent: Continuity achieved
+```
+
+### Multi-Agent Configuration
+
+When you run `fcontext enable <agent>`, the tool generates agent-specific instruction files that point back to `.fcontext/`:
+
+```mermaid
+graph TD
+    FC[".fcontext/<br/>Single Source of Truth"]
+    
+    FC -->|enable copilot| GH[".github/instructions/<br/>fcontext.instructions.md"]
+    FC -->|enable claude| CL[".claude/rules/<br/>fcontext.md"]
+    FC -->|enable cursor| CU[".cursor/rules/<br/>fcontext.md"]
+    FC -->|enable trae| TR[".trae/rules/<br/>fcontext.md"]
+
+    GH --> A1["GitHub Copilot"]
+    CL --> A2["Claude Code"]
+    CU --> A3["Cursor"]
+    TR --> A4["Trae"]
+```
+
+Each instruction file contains:
+
+1. **Workflow rules** — when to read/write `.fcontext/` data
+2. **Anti-pattern rules** — what NOT to do (e.g., never modify `_experiences/`)
+3. **Command reference** — available `fcontext` CLI commands
+
+The instructions are **generated, not copied**. Each agent gets rules formatted for its own instruction system.
+
+---
+
+## Design Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Files over APIs** | All context is plain Markdown/YAML files |
+| **Convention over configuration** | Fixed directory structure, no config needed |
+| **Agent-agnostic** | Shared data, agent-specific instruction generation |
+| **Additive knowledge** | Topics accumulate, nothing is auto-deleted |
+| **Read-only imports** | Experience packs are immutable once imported |
+| **Local-first** | No network required for core functionality |