project-scriber 1.0.0__tar.gz

project_scriber-1.0.0/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

project_scriber-1.0.0/.idea/ProjectScriber.iml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.12 virtualenv at D:\Projects\ProjectScriber\.venv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="TestRunnerService">
+    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+  </component>
+</module>

project_scriber-1.0.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

project_scriber-1.0.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.12 virtualenv at D:\Projects\ProjectScriber\.venv" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.12 virtualenv at D:\Projects\ProjectScriber\.venv" project-jdk-type="Python SDK" />
+</project>

project_scriber-1.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/ProjectScriber.iml" filepath="$PROJECT_DIR$/.idea/ProjectScriber.iml" />
+    </modules>
+  </component>
+</project>

project_scriber-1.0.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

project_scriber-1.0.0/.idea/workspace.xml

@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="09762ee6-9485-49bb-a710-9afbb60e51eb" name="Changes" comment="Initial commit of ProjectScriber">
+      <change afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/scriber_icon.svg" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/scriber_logo.svg" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/assets/scriber_name.svg" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/run.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/scriber/__init__.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/scriber/cli.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/scriber/core.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/tests/test_suite.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/LICENSE" beforeDir="false" afterPath="$PROJECT_DIR$/LICENSE" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="GitHubPullRequestSearchHistory">{
+  &quot;lastFilter&quot;: {
+    &quot;state&quot;: &quot;OPEN&quot;,
+    &quot;assignee&quot;: &quot;SunneV&quot;
+  }
+}</component>
+  <component name="GithubPullRequestsUISettings">{
+  &quot;selectedUrlAndAccountId&quot;: {
+    &quot;url&quot;: &quot;https://github.com/SunneV/ProjectScriber.git&quot;,
+    &quot;accountId&quot;: &quot;305303c5-3fbb-49d5-b80a-c51603759d28&quot;
+  }
+}</component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 0
+}</component>
+  <component name="ProjectId" id="31sejKMEdz9kwnIuwqy6DAVCK45" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent">{
+  &quot;keyToString&quot;: {
+    &quot;Python tests.Python tests in tests.executor&quot;: &quot;Run&quot;,
+    &quot;Python tests.pytest in test_suite.py.executor&quot;: &quot;Run&quot;,
+    &quot;Python.run.executor&quot;: &quot;Run&quot;,
+    &quot;Python.test_suite.executor&quot;: &quot;Run&quot;,
+    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;main&quot;,
+    &quot;last_opened_file_path&quot;: &quot;D:/Projects/ProjectScriber/assets&quot;,
+    &quot;settings.editor.selected.configurable&quot;: &quot;com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable&quot;
+  }
+}</component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="D:\Projects\ProjectScriber\assets" />
+      <recent name="D:\Projects\ProjectScriber" />
+    </key>
+  </component>
+  <component name="RunManager" selected="Python.run">
+    <configuration name="run" type="PythonConfigurationType" factoryName="Python" temporary="true" nameIsGenerated="true">
+      <module name="ProjectScriber" />
+      <option name="ENV_FILES" value="" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="PARENT_ENVS" value="true" />
+      <envs>
+        <env name="PYTHONUNBUFFERED" value="1" />
+      </envs>
+      <option name="SDK_HOME" value="" />
+      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/src" />
+      <option name="IS_MODULE_SDK" value="true" />
+      <option name="ADD_CONTENT_ROOTS" value="true" />
+      <option name="ADD_SOURCE_ROOTS" value="true" />
+      <option name="SCRIPT_NAME" value="$PROJECT_DIR$/src/run.py" />
+      <option name="PARAMETERS" value="" />
+      <option name="SHOW_COMMAND_LINE" value="false" />
+      <option name="EMULATE_TERMINAL" value="false" />
+      <option name="MODULE_MODE" value="false" />
+      <option name="REDIRECT_INPUT" value="false" />
+      <option name="INPUT_FILE" value="" />
+      <method v="2" />
+    </configuration>
+    <configuration name="test_suite" type="PythonConfigurationType" factoryName="Python" temporary="true" nameIsGenerated="true">
+      <module name="ProjectScriber" />
+      <option name="ENV_FILES" value="" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="PARENT_ENVS" value="true" />
+      <envs>
+        <env name="PYTHONUNBUFFERED" value="1" />
+      </envs>
+      <option name="SDK_HOME" value="" />
+      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/tests" />
+      <option name="IS_MODULE_SDK" value="true" />
+      <option name="ADD_CONTENT_ROOTS" value="true" />
+      <option name="ADD_SOURCE_ROOTS" value="true" />
+      <option name="SCRIPT_NAME" value="$PROJECT_DIR$/tests/test_suite.py" />
+      <option name="PARAMETERS" value="" />
+      <option name="SHOW_COMMAND_LINE" value="false" />
+      <option name="EMULATE_TERMINAL" value="false" />
+      <option name="MODULE_MODE" value="false" />
+      <option name="REDIRECT_INPUT" value="false" />
+      <option name="INPUT_FILE" value="" />
+      <method v="2" />
+    </configuration>
+    <configuration name="Python tests in tests" type="tests" factoryName="Autodetect" temporary="true" nameIsGenerated="true">
+      <module name="ProjectScriber" />
+      <option name="ENV_FILES" value="" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="PARENT_ENVS" value="true" />
+      <option name="SDK_HOME" value="" />
+      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/tests" />
+      <option name="IS_MODULE_SDK" value="true" />
+      <option name="ADD_CONTENT_ROOTS" value="true" />
+      <option name="ADD_SOURCE_ROOTS" value="true" />
+      <option name="_new_additionalArguments" value="&quot;&quot;" />
+      <option name="_new_target" value="&quot;$PROJECT_DIR$/tests&quot;" />
+      <option name="_new_targetType" value="&quot;PATH&quot;" />
+      <method v="2" />
+    </configuration>
+    <configuration name="pytest in test_suite.py" type="tests" factoryName="py.test" temporary="true" nameIsGenerated="true">
+      <module name="ProjectScriber" />
+      <option name="ENV_FILES" value="" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="PARENT_ENVS" value="true" />
+      <option name="SDK_HOME" value="" />
+      <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="IS_MODULE_SDK" value="true" />
+      <option name="ADD_CONTENT_ROOTS" value="true" />
+      <option name="ADD_SOURCE_ROOTS" value="true" />
+      <option name="_new_keywords" value="&quot;&quot;" />
+      <option name="_new_parameters" value="&quot;&quot;" />
+      <option name="_new_additionalArguments" value="&quot;&quot;" />
+      <option name="_new_target" value="&quot;$PROJECT_DIR$/tests/test_suite.py&quot;" />
+      <option name="_new_targetType" value="&quot;PATH&quot;" />
+      <method v="2" />
+    </configuration>
+    <recent_temporary>
+      <list>
+        <item itemvalue="Python.run" />
+        <item itemvalue="Python tests.pytest in test_suite.py" />
+        <item itemvalue="Python.test_suite" />
+        <item itemvalue="Python tests.Python tests in tests" />
+      </list>
+    </recent_temporary>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-7e47963ff851-f0eec537fc84-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-252.23892.515" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="09762ee6-9485-49bb-a710-9afbb60e51eb" name="Changes" comment="" />
+      <created>1754140469066</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1754140469066</updated>
+    </task>
+    <servers />
+  </component>
+  <component name="Vcs.Log.Tabs.Properties">
+    <option name="TAB_STATES">
+      <map>
+        <entry key="MAIN">
+          <value>
+            <State />
+          </value>
+        </entry>
+      </map>
+    </option>
+  </component>
+  <component name="VcsManagerConfiguration">
+    <MESSAGE value="Initial commit" />
+    <MESSAGE value="Initial commit of ProjectScriber" />
+    <option name="LAST_COMMIT_MESSAGE" value="Initial commit of ProjectScriber" />
+  </component>
+</project>

project_scriber-1.0.0/.scriber.json

@@ -0,0 +1,41 @@
+{
+  "use_gitignore": true,
+  "exclude": [
+    ".git",
+    ".idea",
+    ".vscode",
+    ".project",
+    ".settings",
+    ".classpath",
+    "__pycache__",
+    "*.pyc",
+    ".venv",
+    "venv",
+    ".pytest_cache",
+    "uv.lock",
+    "node_modules",
+    "npm-debug.log*",
+    "yarn-error.log",
+    "build",
+    "dist",
+    "target",
+    "bin",
+    "obj",
+    "out",
+    "vendor",
+    "bower_components",
+    "*.log",
+    "*.lock",
+    "*.tmp",
+    "temp",
+    "tmp",
+    ".DS_Store",
+    "Thumbs.db",
+    "*~",
+    "*.swp",
+    "*.swo",
+    "scriber_output.txt",
+    ".scriber.json"
+  ],
+  "include": []
+}

project_scriber-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SunneV (Wojciech Mariusz Cichoń)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

project_scriber-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: project-scriber
+Version: 1.0.0
+Summary: An intelligent tool to map, analyze, and compile project source code for LLM context.
+Project-URL: Homepage, https://github.com/SunneV/ProjectScriber
+Project-URL: Issues, https://github.com/SunneV/ProjectScriber/issues
+Author-email: "SunneV (Wojciech Mariusz Cichoń)" <wojciech.m.cichon@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 SunneV (Wojciech Mariusz Cichoń)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: code-analysis,context-builder,developer-tools,llm,source-code
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pathspec
+Requires-Dist: pyperclip
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Requires-Dist: tiktoken
+Requires-Dist: tomli; python_version < '3.11'
+Requires-Dist: tomlkit
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Introduction
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_logo.svg" alt="ProjectScriber Logo" width="420">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_name.svg" alt="ProjectScriber Name" width="300">
+</p>
+
+A command-line tool to intelligently map and compile your entire project's source code into a single, context-optimized
+text file for Large Language Models (LLMs).
+
+ProjectScriber scans your project directory, respects `.gitignore` rules, applies custom filters, and bundles all
+relevant code into a clean, readable format. It's the perfect way to provide a complete codebase to an AI for analysis,
+documentation, or refactoring.
+
+-----
+
+## Key Features
+
+- **🌳 Smart Project Mapping:** Generates a clear and intuitive tree view of your project's structure.
+- **⚙️ Intelligent Filtering:** Automatically respects `.gitignore` rules and supports custom `include` and `exclude`
+  patterns via a `.scriber.json` file for fine-grained control.
+- **📊 In-depth Code Analysis:** Provides a summary with total file size, estimated token count (using `cl100k_base`),
+  and a language breakdown for a quick overview of your codebase.
+- **✨ Interactive Setup:** A simple `scriber init` command walks you through creating a configuration file tailored to
+  your project.
+- **📋 Clipboard Integration:** Use the `--copy` flag to automatically copy the entire consolidated output to your
+  clipboard, ready to be pasted into any application.
+- **🔧 Flexible Configuration:** Manage your settings globally in a `pyproject.toml` file or per-project with a
+  `.scriber.json` file.
+
+-----
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10 or higher.
+
+### Installation
+
+Install the package from the source using pip. For development, include the optional dependencies.
+
+```shell
+# Navigate to the project root directory
+pip install .[dev]
+```
+
+This will install `ProjectScriber` and make the `scriber` command available in your terminal.
+
+-----
+
+## Usage
+
+### 1\. Basic Scan
+
+To run ProjectScriber on the current directory, simply execute the `scriber` command. This will generate a
+`scriber_output.txt` file in the same directory.
+
+```shell
+scriber
+```
+
+To target a different project directory:
+
+```shell
+scriber /path/to/your/project
+```
+
+### 2\. First-Time Configuration
+
+For a new project, run the interactive `init` command to create a `.scriber.json` configuration file. This will guide
+you through setting up rules for ignoring files and respecting `.gitignore`.
+
+```shell
+scriber init
+```
+
+### 3\. Advanced Example
+
+Scan a different project, specify a custom output file, and copy the result to the clipboard all in one command.
+
+```shell
+scriber ../my-other-project --output custom_map.txt --copy
+```
+
+-----
+
+## Commands and Options
+
+You can customize ProjectScriber's behavior with the following commands and options.
+
+| Command/Option        | Alias | Description                                                                    |
+|:----------------------|:-----:|:-------------------------------------------------------------------------------|
+| `scriber [path]`      |       | Targets a specific directory. Defaults to the current working directory.       |
+| `init`                |       | Starts the interactive process to create a `.scriber.json` configuration file. |
+| `--output [filename]` | `-o`  | Specifies a custom name for the output file.                                   |
+| `--copy`              | `-c`  | Copies the final output directly to the clipboard.                             |
+| `--tree-only`         |       | Generates only the folder structure map, excluding all file contents.          |
+| `--config [path]`     |       | Specifies the path to a custom configuration file.                             |
+
+-----
+
+## Configuration
+
+You can control ProjectScriber's behavior by placing a `.scriber.json` file in your project's root, which can be easily
+created with the `scriber init` command.
+
+**Example `.scriber.json`:**
+
+```json
+{
+  "use_gitignore": true,
+  "exclude": [
+    "__pycache__",
+    "node_modules",
+    "*.log"
+  ],
+  "include": [
+    "*.py",
+    "*.js"
+  ]
+}
+```
+
+**Example `pyproject.toml`:**
+
+```toml
+[tool.scriber]
+use_gitignore = true
+exclude = [
+    "__pycache__",
+    "node_modules",
+    "*.log",
+]
+include = [
+    "*.py",
+    "*.js",
+]
+```
+
+- **`use_gitignore`**: If `true`, all patterns in your `.gitignore` file will be used for exclusion.
+- **`exclude`**: A list of file or folder name patterns to explicitly ignore.
+- **`include`**: If provided, *only* files matching these patterns will be included in the output, overriding other
+  rules.
+
+Settings can also be placed in your `pyproject.toml` file under the `[tool.scriber]` section. If a `.scriber.json` file
+is present, it will take precedence over the `pyproject.toml` configuration.

project_scriber-1.0.0/README.md

@@ -0,0 +1,149 @@
+# Introduction
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_logo.svg" alt="ProjectScriber Logo" width="420">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_name.svg" alt="ProjectScriber Name" width="300">
+</p>
+
+A command-line tool to intelligently map and compile your entire project's source code into a single, context-optimized
+text file for Large Language Models (LLMs).
+
+ProjectScriber scans your project directory, respects `.gitignore` rules, applies custom filters, and bundles all
+relevant code into a clean, readable format. It's the perfect way to provide a complete codebase to an AI for analysis,
+documentation, or refactoring.
+
+-----
+
+## Key Features
+
+- **🌳 Smart Project Mapping:** Generates a clear and intuitive tree view of your project's structure.
+- **⚙️ Intelligent Filtering:** Automatically respects `.gitignore` rules and supports custom `include` and `exclude`
+  patterns via a `.scriber.json` file for fine-grained control.
+- **📊 In-depth Code Analysis:** Provides a summary with total file size, estimated token count (using `cl100k_base`),
+  and a language breakdown for a quick overview of your codebase.
+- **✨ Interactive Setup:** A simple `scriber init` command walks you through creating a configuration file tailored to
+  your project.
+- **📋 Clipboard Integration:** Use the `--copy` flag to automatically copy the entire consolidated output to your
+  clipboard, ready to be pasted into any application.
+- **🔧 Flexible Configuration:** Manage your settings globally in a `pyproject.toml` file or per-project with a
+  `.scriber.json` file.
+
+-----
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10 or higher.
+
+### Installation
+
+Install the package from the source using pip. For development, include the optional dependencies.
+
+```shell
+# Navigate to the project root directory
+pip install .[dev]
+```
+
+This will install `ProjectScriber` and make the `scriber` command available in your terminal.
+
+-----
+
+## Usage
+
+### 1\. Basic Scan
+
+To run ProjectScriber on the current directory, simply execute the `scriber` command. This will generate a
+`scriber_output.txt` file in the same directory.
+
+```shell
+scriber
+```
+
+To target a different project directory:
+
+```shell
+scriber /path/to/your/project
+```
+
+### 2\. First-Time Configuration
+
+For a new project, run the interactive `init` command to create a `.scriber.json` configuration file. This will guide
+you through setting up rules for ignoring files and respecting `.gitignore`.
+
+```shell
+scriber init
+```
+
+### 3\. Advanced Example
+
+Scan a different project, specify a custom output file, and copy the result to the clipboard all in one command.
+
+```shell
+scriber ../my-other-project --output custom_map.txt --copy
+```
+
+-----
+
+## Commands and Options
+
+You can customize ProjectScriber's behavior with the following commands and options.
+
+| Command/Option        | Alias | Description                                                                    |
+|:----------------------|:-----:|:-------------------------------------------------------------------------------|
+| `scriber [path]`      |       | Targets a specific directory. Defaults to the current working directory.       |
+| `init`                |       | Starts the interactive process to create a `.scriber.json` configuration file. |
+| `--output [filename]` | `-o`  | Specifies a custom name for the output file.                                   |
+| `--copy`              | `-c`  | Copies the final output directly to the clipboard.                             |
+| `--tree-only`         |       | Generates only the folder structure map, excluding all file contents.          |
+| `--config [path]`     |       | Specifies the path to a custom configuration file.                             |
+
+-----
+
+## Configuration
+
+You can control ProjectScriber's behavior by placing a `.scriber.json` file in your project's root, which can be easily
+created with the `scriber init` command.
+
+**Example `.scriber.json`:**
+
+```json
+{
+  "use_gitignore": true,
+  "exclude": [
+    "__pycache__",
+    "node_modules",
+    "*.log"
+  ],
+  "include": [
+    "*.py",
+    "*.js"
+  ]
+}
+```
+
+**Example `pyproject.toml`:**
+
+```toml
+[tool.scriber]
+use_gitignore = true
+exclude = [
+    "__pycache__",
+    "node_modules",
+    "*.log",
+]
+include = [
+    "*.py",
+    "*.js",
+]
+```
+
+- **`use_gitignore`**: If `true`, all patterns in your `.gitignore` file will be used for exclusion.
+- **`exclude`**: A list of file or folder name patterns to explicitly ignore.
+- **`include`**: If provided, *only* files matching these patterns will be included in the output, overriding other
+  rules.
+
+Settings can also be placed in your `pyproject.toml` file under the `[tool.scriber]` section. If a `.scriber.json` file
+is present, it will take precedence over the `pyproject.toml` configuration.