icp primer

docs/building-apps/getting-started/app-architecture.mdx

@@ -17,7 +17,7 @@ The application's logic, referred to as the **backend**, can be written in a var
 
 The user interface of the application, referred to as the **frontend**, can contain assets like HTML, CSS, and Javascript.
 
-The most common architecture for an application on ICP is one canister for the frontend and one or more canisters for the backend.
+A common architecture for an application on ICP is one canister for the frontend and one or more canisters for the backend.
 
 <div class="text--center">
   <img
@@ -67,7 +67,7 @@ The `dfx.json` file within the `hello` project directory will define two caniste
 {
   "canisters": {
     "hello_backend": { // Backend canister name
-      "main": "src/hello_backend/main.mo", // Backend canister source code
+      "main": "src/hello_backend/main.mo", // Backend canister source code file
       "type": "motoko" // Canister language
     },
     "hello_frontend": { // Frontend canister name
@@ -213,7 +213,7 @@ The `dfx canister call` command sent a call to the `hello_backend` canister that
 
 Since the method is defined as a `query` method, the canister simply returns data to the caller; it does not alter the canister's code or state.
 
-You can also make this call from the canister's [Candid interface](/docs/building-apps/interact-with-canisters/candid/candid-concepts). Candid is an interface description language used to describe the public interface of a service. [Learn more about Candid](/docs/building-apps/interact-with-canisters/candid/candid-concepts).
+You can also make this call from the canister's [Candid interface](/docs/building-apps/interact-with-canisters/candid/candid-concepts). Candid is an interface description language used to describe the public interface of a canister. [Learn more about Candid](/docs/building-apps/interact-with-canisters/candid/candid-concepts).
 
 ## Application frontend
 
@@ -295,14 +295,22 @@ export default App;
 
 ## Backend and frontend communication
 
-ICP agents are libraries used to make calls to a canister's public interface. Agents are able to send two types of calls to canisters: queries and updates. They can be thought of as 'read only' calls since they cannot change a canister's state and do not go through consensus. Updates do change a canister's state and go through consensus.
+ICP agents are libraries used to make calls to a canister's public interface. Agents are able to send two types of calls to canisters: queries and updates. Queries can be thought of as 'read-only' calls since they cannot change a canister's state and do not go through consensus. Updates do change a canister's state and go through consensus.
 
 When an agent makes a call to a canister, it submits a request to the canister containing the request type, canister ID, method name, and any input or arguments to be passed to the method.
 
 In this example, the frontend provides the user with a text input box and a button to submit the input. When the button is pressed, the ICP JavaScript agent sends a `query` request to the `hello_backend` canister's `greet` method and includes the user's text input.
 
 The backend processes the request, then responds to the agent with an outgoing message that includes the result of the method, in this case, `"Hello, <name>!"`. The agent passes the response to the frontend. How the response is handled by the frontend will vary based on the frontend's purpose, code, and functionality. In this example, it displays the content of the response for the user to read.
 
+<div class="text--center">
+  <img
+    src={useBaseUrl("/img/docs/user-interaction1.svg")}
+    alt="User interaction"
+    width="800"
+  />
+</div>
+
 [Learn more about agents](/docs/building-apps/interact-with-canisters/agents/overview).
 
 ## User interaction
@@ -326,16 +334,6 @@ You will see the user interface. Insert your name into the text box and click "S
   />
 </div>
 
-In the background, the application is executing these steps:
-
-<div class="text--center">
-  <img
-    src={useBaseUrl("/img/docs/user-interaction1.svg")}
-    alt="User interaction"
-    width="800"
-  />
-</div>
-
 
 
 

docs/building-apps/getting-started/icp-primer.mdx

@@ -12,33 +12,33 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
 
 <MarkdownChipRow labels={["Beginner", "Getting started"]} />
 
-The ICP network is made up of **nodes** that each run software known as the **replica**. The replica provides the execution environment for running canisters. A group of interconnected nodes is known as a **subnet**. Subnets vary in size between 13 and 40 nodes.
+The ICP network is made up of **nodes** that each run software known as the **replica**. The replica provides the execution environment for running <GlossaryTooltip>canisters</GlossaryTooltip>. A group of interconnected nodes is known as a **subnet**. Subnets vary in size between 13 and 40 nodes.
 
-Canisters can be deployed to the mainnet, the playground, or the local replica. When a canister is deployed to the mainnet or the playground, it is deployed to a subnet and replicated across all nodes on that subnet, meaning there are multiple instances of the canister running at once in parallel. Canisters are replicated for security, reliability, redundancy, and state consistency. A canister on one subnet can communicate with canisters on another subnet.
+Canisters can be deployed to the mainnet, the playground, or your local machine. When a canister is deployed to the mainnet or the playground, it is deployed to a subnet and replicated across all nodes on that subnet, meaning there are multiple instances of the canister running at once. Canisters are replicated for security, reliability, redundancy, and state consistency. A canister on one subnet can communicate with canisters on another subnet.
 
 <div class="text--center">
   <img
     src={useBaseUrl("/img/docs/icp-primer.png")}
-    alt="Application architecture"
+    alt="Canister replication"
     width="800"
   />
 </div>
 
-Canisters deployed to the local replica are not replicated.
+Canisters deployed to your local machine are not replicated.
 
 ## Canister resource consumption
 
 Canisters require resources like storage, compute, and network bandwidth. When a canister is deployed to the mainnet and running on a subnet, it utilizes the resources provided by that subnet's nodes. Canisters are charged for the resources they use, calls they send, and any operations they perform using features such as HTTPS outcalls, threshold signatures, and the Bitcoin integration API. Each type of canister operation and resource has a different cost associated with it, and costs linearly scale with the number of nodes in the subnet.
 
 A canister pays for resources by burning **cycles**. It's the developer's responsibility to load each of their canisters with adequate cycles, though anyone can send cycles to any canister. This cost model is known as ICP's **reverse gas model**. Developers can obtain cycles by [converting ICP tokens](tokens-and-cycles.mdx) into cycles using `dfx`.
 
-Locally deployed canisters are limited to the resources provided by the local machine and cycles are fabricated for development purposes.
+Locally deployed canisters are limited to the resources provided by the local machine, and cycles are fabricated for development purposes.
 
 ## Canister calls
 
-After you deploy a canister, it can begin receiving and processing requests from users and from other canisters. Canisters that are available to send requests and receive replies are considered in be in a `Running` state.
+After you deploy a canister, it can begin receiving and processing requests from users and from other canisters. Canisters that are available to send requests and receive replies are considered to be in a `Running` state.
 
-A canister's state can be read or modified through the use of query or update calls respectively. Query calls do not go through consensus and do not alter the canister's state, while update calls do go through consensus and can modify canister state. A canister answers the calls it receives in a first-in first-out manner.
+A canister's state can be read or modified through the use of [query](/docs/building-apps/interact-with-canisters/query-calls) or [update](/docs/building-apps/interact-with-canisters/update-calls) calls, respectively. Query calls do not go through consensus and do not alter the canister's state, while update calls do go through consensus and can modify canister state. A canister answers the calls it receives in a first-in, first-out manner.
 
 <div class="text--center">
   <img
@@ -48,13 +48,13 @@ A canister's state can be read or modified through the use of query or update ca
   />
 </div>
 
-Canisters can also make calls to the [management canister](/docs/references/system-canisters/management-canister), which acts as the network's system API used to access features of ICP such as randomness and timers.
+Canisters can also make calls to the [management canister](/docs/references/system-canisters/management-canister), which acts as the network's system API used to access features such as randomness and timers.
 
 ## Canister modifications
 
-A canister's code is mutable. It can be upgraded to apply code changes or reinstalled with an entirely new Wasm module. Changes to the canister, such as upgrades or modifications to the canister's settings, can be executed by the canister's **controllers**. A controller is a [developer identity](/docs/building-apps/getting-started/identities) or another canister that has permission to make such changes.
+A canister's code is mutable. It can be upgraded to apply code changes or reinstalled with an entirely new Wasm module. Changes to the canister, such as upgrades or modifications to the canister's settings, are executed by the canister's **controllers**. A controller is a [developer identity](/docs/building-apps/getting-started/identities) or another canister that has permission to make such changes.
 
-In the initial stages of development, the canister is usually controlled by its developer, which allows the developer to iterate quickly. As the canister becomes mature and production ready, the control over it could move to a decentralized organization (such as an SNS) to make the canister more secure and trustworthy.
+In the initial stages of development, the canister is usually controlled by its developer, which allows the developer to iterate quickly. As the canister becomes mature and production-ready, the control over it could move to a decentralized organization (such as an [SNS](/docs/building-apps/governing-apps/overview)) to make the canister more secure and trustworthy.
 
 <div class="text--center">
   <img

docs/building-apps/getting-started/identities.mdx

@@ -7,7 +7,7 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
 
 # Developer identities
 
-<MarkdownChipRow labels={["Beginner", "Getting started", "Tutorial"]} />
+<MarkdownChipRow labels={["Beginner", "Getting started"]} />
 
 A developer **identity** is essential to developing canisters. Developer identities are basically a private/public key pair. Instead of using the public key as an identifier for the identity, a so-called principal is derived from the public key. The terms **identity** and **principal** are often used interchangeably. For better memorability, every developer identity in `dfx` has a name. The public key of an identity can be distributed openly as it will be used to encrypt messages. The private key must be kept secret and stored securely.
 

docs/building-apps/getting-started/install.mdx

@@ -11,7 +11,7 @@ import { OsType, useOs } from "/src/hooks/useOs";
 
 # Installing the IC SDK
 
-<MarkdownChipRow labels={["Beginner", "Getting started", "Tutorial"]} />
+<MarkdownChipRow labels={["Beginner", "Getting started"]} />
 
 The IC SDK is a software development kit used to develop applications on your local machine and to deploy them to ICP. It is natively supported on Linux or macOS 12.\* Monterey and newer. Windows users can use the IC SDK with Windows Subsystem for Linux (WSL 2).
 

docs/building-apps/getting-started/quickstart.mdx

@@ -7,9 +7,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 import TabItem from "@theme/TabItem";
 import { OsType, useOs } from "/src/hooks/useOs";
 
-# First smart contract
+# Quick start
 
-<MarkdownChipRow labels={["Beginner", "Quick start"]} />
+<MarkdownChipRow labels={["Beginner"]} />
 
 Build Web3, DeFi, fully network-resident social media, games, enterprise apps,
 and just about anything else you can imagine. Your projects are immune to cyberattacks and unstoppable.

docs/building-apps/getting-started/tokens-and-cycles.mdx

@@ -9,7 +9,7 @@ import { AdornedTabs } from "/src/components/Tabs/AdornedTabs";
 
 # Using tokens and cycles
 
-<MarkdownChipRow labels={["Beginner", "Getting started", "Tutorial"]} />
+<MarkdownChipRow labels={["Beginner", "Getting started"]} />
 
 On ICP, there are three types of token assets: ICP tokens, cycles, and ICRC tokens. ICP and cycles are the most important for every developer to understand and use, as they are necessary for deploying and maintaining a canister.
 

docs/building-apps/getting-started/wsl-troubleshoot.mdx

@@ -6,7 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 # WSL troubleshooting
 
-<MarkdownChipRow labels={["Beginner", "Getting started", "Tutorial"]} />
+<MarkdownChipRow labels={["Beginner"]} />
 
 The IC SDK is not natively supported on Windows operating systems. It is recommended for Windows users to install [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install).