# Import System Share docs and templates across projects from Git, npm, or local sources ## Import System Import and sync documentation and templates from external sources. ### Overview The Import System allows you to: - Import docs and templates from Git repositories, npm packages, or local folders - Keep imports synced with their sources - Share patterns and conventions across multiple projects - Reference imported content with `@doc/imports//` ### Quick Start ``` # Import from GitHub knowns import github:knowns-dev/templates --name templates # List all imports knowns import list # Sync to get updates knowns import sync # Reference imported docs # @doc/imports/templates/patterns/component ``` ### Source Types #### Git Repositories ``` # GitHub shorthand knowns import github:user/repo --name my-patterns # GitLab shorthand knowns import gitlab:user/repo --name patterns # Full URL (any Git host) knowns import https://github.com/org/knowledge-base.git --name kb # Specific branch or tag knowns import github:org/templates --ref main --name templates knowns import github:org/templates --ref v1.0.0 --name templates-v1 ``` #### NPM Packages ``` # Latest version knowns import npm:@myorg/patterns --name patterns # Specific version knowns import npm:@myorg/patterns --ref ^1.0.0 --name patterns # Exact version knowns import npm:@myorg/patterns --ref 1.2.3 --name patterns ``` #### Local Folders ``` # Copy files knowns import ./shared-docs --name shared # Symlink (changes reflect immediately) knowns import ./shared-docs --name shared --link # Relative to home knowns import ~/company/patterns --name company ``` ### CLI Commands #### `knowns import add` Add a new import. Shorthand: `knowns import `. ``` knowns import add [options] knowns import [options] # shorthand ``` | Option | Description | |---------------------------|----------------------------------------------| | `-n, --name ` | Custom name for the import | | `-t, --type ` | Force source type: `git`, `npm`, `local` | | `-r, --ref ` | Git branch/tag or npm version | | `--include ` | Include only matching files (glob patterns) | | `--exclude ` | Exclude matching files (glob patterns) | | `--link` | Symlink local imports instead of copying | | `-f, --force` | Overwrite existing import | | `--dry-run` | Preview without writing files | | `--plain` | Plain text output (for AI) | **Examples:** ``` # Import only markdown docs knowns import github:org/repo --name docs --include "**/*.md" # Exclude tests knowns import github:org/repo --name patterns --exclude "**/*.test.*" # Preview what would be imported knowns import github:org/repo --name preview --dry-run ``` #### `knowns import list` List all configured imports with their status. ``` knowns import list [options] ``` | Option | Description | |------------|----------------------------------------------------| | `--plain` | Plain text output (for AI) | **Output includes:** - Import name and source - Last sync date - Number of files - Sync status #### `knowns import sync` Update imports from their sources. ``` knowns import sync [name] [options] ``` | Option | Description | |----------------------|--------------------------------------------------| | `-f, --force` | Overwrite locally modified files | | `--dry-run` | Preview changes without applying | | `--plain` | Plain text output (for AI) | **Examples:** ``` # Sync all imports knowns import sync # Sync specific import knowns import sync patterns # Preview sync changes knowns import sync --dry-run # Force sync (overwrite local changes) knowns import sync patterns --force ``` #### `knowns import remove` Remove an import configuration. ``` knowns import remove [options] ``` | Option | Description | |----------------------|--------------------------------------------------| | `--delete` | Also delete the imported files | | `--plain` | Plain text output (for AI) | **Examples:** ``` # Remove config only (keep files) knowns import remove old-patterns # Remove config and files knowns import remove old-patterns --delete ``` ### Import Structure When you import content, it's organized as: ``` .knowns/ ├── imports.json # Import configurations ├── docs/ │ └── imports/ │ ├── patterns/ # Import named "patterns" │ │ ├── auth.md │ │ └── api.md │ └── templates/ # Import named "templates" │ └── component.md └── templates/ └── patterns/ # Templates from "patterns" import └── react-component/ ``` #### `imports.json` Stores import metadata: ``` { "patterns": { "source": "github:myorg/patterns", "type": "git", "ref": "main", "lastSync": "2025-01-25T10:30:00Z", "files": 15 } } ``` ### Referencing Imported Content #### In Tasks ``` knowns task create "Add auth" \ -d "Implement auth following @doc/imports/patterns/auth" ``` #### In Documentation ``` # API Guidelines See our shared patterns: @doc/imports/patterns/api Related: @doc/imports/templates/rest-endpoint ``` #### In Templates Link imported documentation in `_template.yaml`: ``` description: "API endpoint generator" doc: "imports/patterns/api" # References imported doc ``` ### Workflows #### Team Pattern Library Share patterns across all team projects: ``` # In each project knowns import github:myorg/patterns --name patterns # Keep updated knowns import sync patterns ``` #### Monorepo Shared Docs Share docs between packages in a monorepo: ``` # In packages/app knowns import ../../shared/docs --name shared --link # Changes in shared/docs reflect immediately ``` #### Versioned Templates Use specific versions of templates: ``` # Production: stable version knowns import npm:@myorg/templates --ref ^1.0.0 --name templates # Development: latest knowns import npm:@myorg/templates --ref latest --name templates-dev ``` ### Best Practices #### 1. Use Meaningful Names ``` # Good: descriptive names knowns import github:org/api-patterns --name api-patterns knowns import github:org/ui-components --name ui-components # Avoid: generic names knowns import github:org/stuff --name stuff ``` #### 2. Pin Versions for Stability ``` # Production: pin to specific version knowns import npm:@org/patterns --ref 1.2.3 --name patterns # Development: allow minor updates knowns import npm:@org/patterns --ref ^1.2.0 --name patterns ``` #### 3. Use Include/Exclude Filters Import only what you need: ``` # Only docs, no tests or examples knowns import github:org/repo \ --name patterns \ --include "docs/**/*.md" \ --exclude "**/*.test.*" ``` #### 4. Sync Regularly Add to your workflow: ``` # Before starting work knowns import sync # Or automate in CI/CD knowns import sync --force ``` #### 5. Preview Before Importing Always preview first: ``` # See what would be imported knowns import github:org/large-repo --name test --dry-run # Then import knowns import github:org/large-repo --name patterns ``` ### Troubleshooting #### Import Failed ``` # Check source is accessible git ls-remote https://github.com/org/repo # For npm, check package exists npm view @org/package # Try with verbose output knowns import github:org/repo --name test --plain ``` #### Sync Conflicts When local files were modified: ``` # Preview conflicts knowns import sync patterns --dry-run # Force overwrite local changes knowns import sync patterns --force # Or backup and re-import knowns import remove patterns knowns import github:org/patterns --name patterns ``` #### Large Imports For large repositories: ``` # Filter to specific folders knowns import github:org/large-repo \ --name docs \ --include "docs/**/*" # Or specific file types knowns import github:org/repo \ --name patterns \ --include "**/*.md" ```