docs: tightens up many docs (#109)

# Motivation
<!-- Why is this change necessary? -->

# Content
<!-- Please include a summary of the change -->
# Testing
<!-- How was the change tested? -->
# Please check the following before marking your PR as ready for review

- [ ] I have added tests for my changes
- [ ] I have updated the documentation or added new documentation as
needed
- [ ] I have read and agree to the [Contributor License
Agreement](../CLA.md)

---------

Co-authored-by: codegen-bot <[email protected]>

Author: jayhack

README.md

@@ -24,10 +24,34 @@ for function in codebase.functions:
 
 Write code that transforms code. Codegen combines the parsing power of [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) with the graph algorithms of [rustworkx](https://github.com/Qiskit/rustworkx) to enable scriptable, multi-language code manipulation at scale.
 
-## Installation
+## Installation and Usage
 **This library requires Python 3.12 – 3.13.**
 ```
+# Install inside existing project
 uv pip install codegen
+
+# Install global CLI
+uv tool install codegen
+
+# Create a codemod for a given repo
+cd path/to/repo
+codegen init
+codegen create test-function
+
+# Run said codemod
+codegen run test-function
+
+# Create an isolated venv with codegen => open jupyter
+codegen notebook
+```
+
+## Usage
+
+See [https://docs.codegen.com/introduction/getting-started] for a full tutorial.
+
+```
+from codegen import Codebase
+
 ```
 
 ## Resources

docs/blog/act-via-code.mdx

@@ -92,7 +92,7 @@ Provided a sufficiently comprehensive set of APIs, this paradigm has many clear
 
 For software engineering, we believe the path forward is clear: agents need a framework that matches how developers think about and manipulate code. While decades of static analysis work gives us a strong foundation, traditional code modification frameworks weren't designed with AI-human collaboration in mind - they expose low-level APIs that don't match how developers (or AI systems) think about code changes.
 
-We're building a framework with high-level APIs that correspond to how engineers actually think about code modifications. The APIs are clean and intuitive, following clear [principles](/docs/principles) that eliminate sharp edges and handle edge cases automatically. Most importantly, the framework encodes rich structural understanding of code. Consider this example:
+We're building a framework with high-level APIs that correspond to how engineers actually think about code modifications. The APIs are clean and intuitive, following clear [principles](/introduction/guiding-principles) that eliminate sharp edges and handle edge cases automatically. Most importantly, the framework encodes rich structural understanding of code. Consider this example:
 
 ```python
 # Access to high-level semantic operations
@@ -107,7 +107,7 @@ This isn't just string manipulation - the framework understands React component
 
 The documentation for such a framework isn't just API reference - it's education for advanced intelligence about how to successfully manipulate code at scale. We're building for a future where AI systems are significant contributors to codebases, and they need to understand not just the "how" but the "why" behind code manipulation patterns.
 
-Crucially, we believe these APIs will extend beyond the codebase itself into the broader software engineering ecosystem. When agents can seamlessly interact with tools like Datadog, AWS, and other development platforms through the same clean interfaces, we'll take a major step toward [autonomous software engineering](/about#our-mission). The highest leverage move isn't just giving agents the ability to modify code - it's giving them programmatic access to the entire software development lifecycle.
+Crucially, we believe these APIs will extend beyond the codebase itself into the broader software engineering ecosystem. When agents can seamlessly interact with tools like Datadog, AWS, and other development platforms through the same clean interfaces, we'll take a major step toward [autonomous software engineering](/introduction/about#our-mission). The highest leverage move isn't just giving agents the ability to modify code - it's giving them programmatic access to the entire software development lifecycle.
 
 ## Codegen is now OSS
 

docs/building-with-codegen/symbol-api.mdx

@@ -5,13 +5,13 @@ icon: "shapes"
 iconType: "solid"
 ---
 
-The [`Symbol`](/api-reference/core/Symbol) is the primary way developers interact with code in Codegen. It maps to how developers think about code - as functions, classes, variables, and other named entities.
+The [Symbol](/api-reference/core/Symbol) is the primary way developers interact with code in Codegen. It maps to how developers think about code - as functions, classes, variables, and other named entities.
 
-Both the [`Function`](/api-reference/core/Function) and [`Class`](/api-reference/core/Class) symbols are subclasses of the [`Symbol`](/api-reference/core/Symbol) class.
+Both the [Function](/api-reference/core/Function) and [Class](/api-reference/core/Class) symbols are subclasses of the [Symbol](/api-reference/core/Symbol) class.
 
 ## Accessing Symbols
 
-The [`Codebase`](/api-reference/core/Codebase) class provides getters and iterators for functions, classes and symbols:
+The [Codebase](/api-reference/core/Codebase) class provides getters and iterators for functions, classes and symbols:
 
 ```python
 # Core symbol types
@@ -32,17 +32,17 @@ for symbol in codebase.functions + codebase.classes:
 
 All symbols share common APIs for manipulation:
 
-- The [`Editable`](/api-reference/core/Editable) API
+- The [Editable](/api-reference/core/Editable) API
 - Metadata
-  - [`symbol.name`](/api-reference/core/Symbol#name)
-  - [`symbol.source`](/api-reference/core/Symbol#source)
-  - [`symbol.docstring`](/api-reference/core/Symbol#docstring)
+  - [symbol.name](/api-reference/core/Symbol#name)
+  - [symbol.source](/api-reference/core/Symbol#source)
+  - [symbol.docstring](/api-reference/core/Symbol#docstring)
 - Edit operations
-  - [`symbol.set_docstring`](/api-reference/core/Symbol#add_comment)
-  - [`symbol.move_to_file`](/api-reference/core/Symbol#move-to-file) (see [Moving Symbols](/building-with-codegen/moving-symbols))
+  - [symbol.set_docstring](/api-reference/core/Symbol#add_comment)
+  - [symbol.move_to_file](/api-reference/core/Symbol#move-to-file) (see [Moving Symbols](/building-with-codegen/moving-symbols))
 - Graph relations (See [Usages and Dependencies](/building-with-codegen/dependencies-and-usages))
-  - [`symbol.usages`](/api-reference/core/Symbol#usages)
-  - [`symbol.dependencies`](/api-reference/core/Symbol#dependencies)
+  - [symbol.usages](/api-reference/core/Symbol#usages)
+  - [symbol.dependencies](/api-reference/core/Symbol#dependencies)
 
 ## Name operations
 

docs/introduction/community.mdx

@@ -36,35 +36,6 @@ Join the growing Codegen community! We're excited to have you be part of our jou
   Please help us improve this library and documentation by submitting a PR!
 </Tip>
 
-## Community Channels
-
-### Slack
-
-Our [Slack community](https://community.codegen.com) is where you can:
-
-- Get help and support
-- Share your Codegen projects
-- Connect with other developers
-- Stay updated on new features
-
-### GitHub
-
-Codegen is [open source](https://github.com/codegen-sh/codegen-sdk) and we welcome contributions! On GitHub you can:
-
-- Report issues
-- Submit pull requests
-- Star the project
-- Browse the source code
-
-### Twitter (X)
-
-Follow us on [Twitter/X](https://x.com/codegen) to:
-
-- Get the latest updates
-- See community highlights
-- Connect with the team
-- Share your Codegen wins
-
 ## Contributing
 
 We welcome contributions of all kinds! Whether you're fixing a typo in documentation, reporting a bug, or implementing a new feature, we appreciate your help in making Codegen better.
@@ -75,5 +46,3 @@ Check out our [Contributing Guide](https://github.com/codegen-sh/codegen-sdk/blo
 - Submit pull requests
 - Report issues
 - Contribute to documentation
-
-Together, we can build better tools for code transformation!

docs/introduction/faq.mdx

@@ -48,8 +48,8 @@ iconType: "solid"
   </Accordion>
   <Accordion title="Where can I get help if I'm stuck?" icon="life-ring">
     The best places to get help are:
-    1. Our community Slack channel
-    2. GitHub issues for bug reports
+    1. Our community [Slack channel](https://community.codegen.com)
+    2. [GitHub issues](https://github.com/codegen-sh/codegen-sdk) for bug reports
     3. Reach out to us on [Twitter](https://x.com/codegen)
   </Accordion>
 </AccordionGroup>

docs/introduction/how-it-works.mdx

@@ -21,7 +21,7 @@ Codegen performs advanced static analysis to build a rich graph representation o
 
 ## The Codebase Graph
 
-At the heart of Codegen is a comprehensive graph representation of your code. When you initialize a `[Codebase](/api-reference/core/Codebase)`, it performs static analysis to construct a rich graph structure connecting code elements:
+At the heart of Codegen is a comprehensive graph representation of your code. When you initialize a [Codebase](/api-reference/core/Codebase), it performs static analysis to construct a rich graph structure connecting code elements:
 
 ```python
 # Initialize and analyze the codebase

docs/introduction/overview.mdx

@@ -9,24 +9,16 @@ iconType: "solid"
 
 It provides a scriptable interface to a powerful, multi-lingual language server built on top of [Tree-sitter](https://tree-sitter.github.io/tree-sitter/).
 
-export const intoSnippet = `# grabs codebase content
-
-file = codebase.files[0] # or .get_file("test.py")
-function = codebase.functions[0] # or .get_symbol("my_func")
-
-# print logs
-
-print(f'# of files: {len(codebase.files)}')
-print(f'# of functions: {len(codebase.functions)}')
-
-# make edits
-
-file.edit('🌈' + file.content) # edit contents
-function.rename('new_name') # rename
-function.set_docstring('new docstring') # set docstring
-
-# ... etc.
-
+export const intoSnippet = `# Codegen builds a complete graph connecting
+#  functions, classes, imports and their relationships
+from codegen import Codebase
+
+# Work with code without dealing with syntax trees or parsing
+for function in codebase.functions:
+    # Comprehensive static analysis for references, dependencies, etc.
+    if not function.usages:
+        # Auto-handles references and imports to maintain correctness
+        function.remove()
 `
 
 <iframe
@@ -45,7 +37,11 @@ function.set_docstring('new docstring') # set docstring
 ## Installation
 
 ```bash
+# Install CLI
 uv tool install codegen
+
+# Install inside existing project
+pip install codegen
 ```
 
 ## Get Started
@@ -86,7 +82,7 @@ Codegen was engineered backwards from real-world refactors we performed for ente
 
 As AI becomes increasingly sophisticated, we're seeing a fascinating shift: AI agents aren't bottlenecked by their ability to understand code or generate solutions. Instead, they're limited by their ability to efficiently manipulate codebases. The challenge isn't the "brain" - it's the "hands."
 
-We built Codegen with a key insight: future AI agents will need to ["act via code,"](https://voyager.minedojo.org/) building their own sophisticated tools for code manipulation. Rather than generating diffs or making direct text changes, these agents will:
+We built Codegen with a key insight: future AI agents will need to ["act via code,"](/blog/act-via-code) building their own sophisticated tools for code manipulation. Rather than generating diffs or making direct text changes, these agents will:
 
 1. Express transformations as composable programs
 2. Build higher-level tools by combining primitive operations

docs/introduction/work-with-ai.mdx

@@ -96,39 +96,3 @@ This will ensure that the IDE's native chat model is aware of the APIs and commo
 ## Devin, OpenHands and Semi-autonomous Code Agents
 
 <Warning>Coming soon!</Warning>
-
-## Coming Soon
-
-<CardGroup cols={2}>
-  <Card title="Default System Prompts" icon="download">
-    Pre-built prompts for common transformation scenarios, ready to use with any
-    AI.
-  </Card>
-  <Card title="Upgrade Paths" icon="arrow-up-right-dots">
-    Specialized prompts for specific upgrade paths (React, TypeScript, etc.).
-  </Card>
-</CardGroup>
-
-## Best Practices
-
-1. **Use Generated Prompts**: Let Codegen generate system prompts instead of writing them manually. They include important context about your codebase.
-
-2. **Be Specific**: When creating a codemod, provide detailed descriptions to help the AI understand your goals:
-
-   ```bash
-   codegen create migrate-api --description "Update API calls to use the new v2 endpoints, handling pagination and error responses"
-   ```
-
-3. **Leverage Context**: In Cursor, always @mention your codemod to give the AI full context about your transformation.
-
-4. **Iterative Refinement**: Use AI suggestions as a starting point, then refine based on your specific needs.
-
-<Note>
-  The system prompts are designed to be human-readable. Review them to
-  understand what context is being provided to the AI.
-</Note>
-
-<Tip>
-  You can also use the generated system prompts with other AI tools - just copy
-  the prompt content and paste it into your preferred AI interface.
-</Tip>